Some feedback on the website.

[H. S. Teoh via Digitalmars-d]

On Sat, Dec 19, 2015 at 09:58:44AM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> On 12/19/15 12:01 AM, Jakob Ovrum wrote:
> >After further changes I was able to add `Params:` and `Returns:` with
> >some valuable information, but it also comes with a fair amount of
> >redundancy. I think a lot of our current functions have more than
> >adequately documented parameters and return values, just without
> >using sections. Some redundancy can be a good thing, but for most of
> >those functions I don't see how simple-mindedly adding purely
> >redundant information is impactful.
> >
> >The important thing is not those sections but that parameters and
> >return values are documented.
> 
> Agreed there's got to be measure in everything. I'm thinking in those
> cases the existing documentation should be reformatted with the
> standard sections.
> 
> When you do standard-formatted documentation for many functions at
> once, it seems kinda trite. But for folks who work on some program and
> want to look up one function, reliance on a standard uniform format is
> very helpful.
[...]

Yes, Walter has said the same thing before. Where the description is too
short to warrant being in both a standard section and in prose, put it
in the standard section. I'd even propose that it's OK to leave the
function description blank if the info in the standard Params: and
Returns: sections already fully define what it does.  This isn't as
literary, but we're writing reference documentation, not an essay
contest, and consistently having information in standard sections makes
it more useful as a reference.


T

-- 
"Hi." "'Lo."