Worst Phobos documentation evar!

[Joseph Rushton Wakeling via Digitalmars-d]

On 28/12/14 03:55, Xinok via Digitalmars-d wrote:
> I'd like to contribute to the documentation (more within my skill level
> anyways), but I'd like to follow some solid guidelines if I'm to do so. If we
> don't have something like it already, perhaps we could create a page on the wiki
> with some tips and conventions for writing documentation for Phobos (and if we
> do, give me a link!). Then of course, we can incorporate some good and bad
> examples which you've provided for us already.

Yup, clear rules for how things should be documented are really necessary.  Then 
it's trivial to find rulebreakers and fix them.

A speculative thought, given the remarks by Manu and others on how templated 
signatures create hassle for comprehension.  Is there any sane way that we could 
auto-generate a "quasi-signature" for functions with the template types 
specified?  The idea would be that e.g. we could have the general signature, and 
then provide a trivial example of how that signature resolves to something saner 
if you know that (say) the input range is a built-in string, or built-in array, 
or whatever.

So, say, you could have the general signature

     S doSomethingWithAString(S s, ...) if (isSomeString!S)

and a note underneath providing the example with S == string:

     string doSomethingWithAString(string s, ...)

Not sure if that's not too much work compared to just proper documentation, but 
thought I'd float it.

BTW is it just me, or are the various isSomething methods of std.traits not 
having documentation generated properly?  See:
http://dlang.org/phobos/std_traits.html

... and try searching for, say, isBoolean, or isSomeString.