Worst Phobos documentation evar!

Joseph Rushton Wakeling via Digitalmars-d digitalmars-d at puremagic.com
Wed Dec 31 05:50:34 PST 2014


On 28/12/14 02:00, Walter Bright via Digitalmars-d wrote:
> Anyone want to take this on? There's a lot of stuff like this in Phobos. It's
> too much for one person to tackle, but if each of us just pick a function here
> and there, we can crowdsource and improve things greatly.

Just been having a play with documenting Params/Returns for the free functions 
in std.random.  A number of issues encountered.

First, it looks like the build system has changed since I last tried building 
docs.  If I go with 'make html' in my local phobos branch, the various html 
files generated are all empty -- with their content seemingly intended to be 
filled by javascript which doesn't work.  What gives? :-(

Second and more importantly, I ran into some tricky cases implementing Params: 
lists for functions that have multiple overloads with different parameter lists. 
  As things are, it's convenient -- in terms of reading the code -- to have 
different functions ordered from simple to complex signatures, with one 
documentation block for the first, and everything else sharing the same 
documentation using /// ditto.  However, this won't work with a Params: list 
because ddoc attempts to match listed parameters to those of the immediately 
following function signature.

Trivial example:

/**
  * Params:
  *     rng = (optional) random number generator to use;
  *           if not specified, defaults to $(D rndGen)
  *
  * Returns:
  *     Floating-point random variate of type $(D T) drawn from the uniform
  *     distribution across the half-open interval [0, 1$(RPAREN).
  */
T uniform01(T = double)()
     if (isFloatingPoint!T)
{
     return uniform01!T(rndGen);
}

/// ditto
T uniform01(T = double, UniformRNG)(ref UniformRNG rng)
     if (isFloatingPoint!T && isUniformRNG!UniformRNG)
out (result)
{
     assert(0 <= result);
     assert(result < 1);
}
body
{
     ...
}

The above will generate a warning because, of course, the first function 
signature doesn't have a parameter 'rng'.  Since docs are compiled with -w, I 
believe this will result in an error ... ?

In the above case, of course, it's trivial just to swap the order of the 
functions, but in general this is not the case, and it's rather irritating to 
have to tweak everything so that functions are listed in order of 
complex-to-simple signatures rather than simple-to-complex.

It's also not clear to me that one can in general avoid cases where there is a 
group of functions, all doing the same thing, where nevertheless there is no 
single function signature accepting all the possible parameters; and yet, it's 
still very convenient to group together the documentation of those function 
signatures.


More information about the Digitalmars-d mailing list