Re: [boost] [Endian] Review / Comments

Subject: Re: [boost] [Endian] Review / Comments
From: Tim Blechmann (tim_at_[hidden])
Date: 2011-09-09 05:16:19

hi beman,

> > documentation
> > the documentation in general is pretty short, but sufficient: the
> > concepts of the library are easy, so there is no need to go into more
> > details. however i would prefer if the documentation uses
> > quickbook/boostbook. most of the recent boost libraries have a very
> > similar layout of the documentation, but the boost.endian docs do not
> > follow these conventions.
> 
> quickbook/boostbook has matured, so I'll take a look. But no promises.
> 
> > also the docs for `conversion functions' and for `integer types' are
> > separate. personally i'd prefer if they could go into the same
> > document, maybe having a structure like: introduction, integer types,
> > conversion functions, examples, reference
> 
> A lot depends on what the conversion functions look like coming out of
> the review. It may make sense to integrate them much more tightly, but
> again, no promises.
> 
> > (preferably doxygen-generated).
> 
> I'm not a fan of doxygen.

well, one may like doxygen or not, i am not a big fan of doxygen, either. but 
it still generates a reasonably good documentation with cross-references and 
the like.

one other point ... the help file seems to directly link to the c++ headers. 
this should be changed:

* some browsers (at least chromium) will not display the header when clicking 
  the link, but will save them on disk.

* providing a direct link to the source code from the docs implies that the 
  user will get some information that are necessary to use the library by 
  reading the sources. imo, this is not the case for using boost.endian.

* if a user opens integer.hpp, the first 60 lines just contain copyright, some
  historical notes, compiler-specific stuff, includes and ifdefs. imo, this is
  the implementation part, which should not be exposed to a user.

so i'd suggest to completely remove the links to the c++ headers.

cheers, tim