Re: [boost] [random] documentation rewrite

Subject: Re: [boost] [random] documentation rewrite
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2009-11-26 11:07:23

AMDG

John Maddock wrote:
> In "Uniform Random Number Generator" it says that the range can be 
> fixed only after the object is constructed, what values do max_value 
> and min_value have in that case?

If the min and max values are not known at compile time, then min_value and
max_value should not be defined and has_fixed_range should be false.
(This is somewhat clunky and I don't think anything in the library uses
min_value and max_value.  Since the standard doesn't have these members,
I'd like to deprecate them.)

> In "Quasi-Random Number Generators" the text "[Does anyone have a 
> model?] " probably needs replacing with something?

Yep.  I don't know that it's worth mentioning Quasi-Random Number Generators
at all, since the library doesn't provide any.

> In Table 1.5 what does the relative speed indicate?  Is smaller 
> better? Or...?

Larger is better.  It's stated above the table.  It appears to be scaled
so that mt19937 is 100.  I'll change the entries to match the Performance
section, which has the heading "relative speed compared to fastest 
[percent]."
Is that clearer?

> Table 1.6 could use updating with more modern machines/compilers.

I'm working on generating quickbook automatically from the
output of random_speed.cpp.

> Table 1.7 has some entries with just a "?", you might find some help 
> in describing these distributions from 
> http://www.boost.org/doc/libs/1_41_0/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists.html, 
> or then again you may not ;-)

Thanks.  I'll take a look.

> In "Header <boost/random/additive_combine.hpp>" the synopsis flows off 
> the page, some of the others are probably too wide as well.  I find 
> generating a PDF and then checking all the "No space for an element, 
> trying to recover" messages a good way to track these down.  Might 
> need some changes to the code formatting to make these readable if 
> they're Doxygen generated?  Let me know if you need help in PDF 
> generation.

Fixing this will probably require changes to the BoostBook stylesheets.
The original code is split onto multiple lines.

> Performance section could probably use more up to date numbers.
>
> I've only skimmed the reference section, but I did notice that the 
> lagged_fibanacci types lacked references.

Yep.  I've been slowly tracking down missing references.

In Christ,
Steven Watanabe