Re: [boost] [random] new documentation

Subject: Re: [boost] [random] new documentation
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2010-02-22 10:53:14

Joachim Faulhaber wrote:
> 2010/2/22 Steven Watanabe <watanabesj_at_[hidden]>
> > John Maddock wrote:
> >
> >> This is hopefully the final version of the work I did back
> >> in November
> >>> to convert the Random docs to Quickbook/Doxygen/Boostbook.
> >>
> >> Steven, I've only scanned those docs a little but this
> >> looks really good:
> >> much better than the old documentation!
> >>
> >> One thing I did notice were some very long lines in the
> >> reference section, for example:
> >>
> >> http://www.cs.hmc.edu/~swatanabe/random_doc/libs/random/doc/html/boost/taus88.html
> >>
> >> These are verging on the unreadable in HTML, but will just
> >> get truncated in PDF output :-(
> >>
> >> I suspect though that this is Doxygen mangling the formatting?
> >
> > Yep.  You mentioned this before, but I couldn't find a way
> > to force it to be formatted properly.  The best I can think of
> > would be to get rid of the long type name and change it to
> > something like
> >
> > typedef xor_combine<...> taus88;
> >
> > for doxygen builds.

I suppose that intermediate typedefs are not desirable?  They could be put in the detail namespace:

namespace detail
{
   typedef random::linear_feedback_shift< uint32_t, 32, 31, 13, 12, 0 > type1;
   typedef random::linear_feedback_shift< uint32_t, 32, 29, 2, 4, 0 > type2;
   typedef random::xor_combine< detail::type1, 0, detail::type2, 0, 0 > type3;
   typedef random::linear_feedback_shift< uint32_t, 32, 28, 3, 17, 0 > type4;
}

typedef random::xor_combine< detail::type3, 0, detail::type4, 0, 0 > taus88;

I think that's easier to read just because the separate parts can be parsed and digested more easily.

> > I have the same problem in my reference section. E.g.
> > http://www.herold-faulhaber.de/boost_itl/doc/libs/itl/doc/html/boost/itl/interval_map.html
>
> If someone knew a trick for a better formatting result, I'd be very
> interested.

typedef interval_base_map< type, DomainT, CodomainT, Traits, Compare, Combine, Section, Interval, Alloc > base_type;

That doesn't help with the base class type, however, and there are still plenty of long sequences of tokens in that class definition.

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.