Suggestion re the manual

[bauss]

On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:
> I am not an expert programmer (although I work in software 
> every day). I'm more of a system designer. Dlang has really 
> made a big difference in our little company and we are truly 
> grateful to have it. However, one thing I miss from my PHP days 
> (I know - script languages - Ugh), is having public comments 
> below each manual page.
>
> Having the public post examples, gotchas, and other helpful 
> information made a world of difference in learning the PHP 
> language, all the while having the "source of truth" directly 
> above.
>
> Just suggesting that it might help increase adoption rates (PHP 
> is very popular). Managing comments does take time, but then so 
> does managing this forum.
>
> Anyway, no ideas are bad ideas, so I felt I should post. I hope 
> it is helpful.

Personally, I don't like it. I don't think good documentation 
needs comments to explain the content.

The reason why it's good for PHP is mostly because of how 
unintuitive and inconsistent it really is sometimes.

As you said yourself, it's good for gotchas etc.

D doesn't really have any gotchas in that sense since it's much 
more strict, not just in the sense of its language, but also how 
the standard library is written.

Most gotchas in PHP stem from inconsistent function names, 
arguments and the fact it's dynamic typing.

D has very consistent naming of functions, order of arguments and 
it's static typed.

Most other language documentations don't have a comment section 
either and probably because they're documented well too.

While PHP has improved and keeps improving, then it still let's 
most of is garbage linger around.