Re: [boost] [Iterator] [PR] Fix for documentation #8010

Subject: Re: [boost] [Iterator] [PR] Fix for documentation #8010
From: Nathan Wilson (nwilson20_at_[hidden])
Date: 2016-01-28 23:23:14

Hi Paul,

Thanks for the info and reply.  That does seem like it would be an arduous
task, and documentation is certainly better at the time the code is written.

Fortunately I'm just looking to make this part of the documentation
accurate. On that note, there is also a sentence in the Abstract of the
Iterator documentation which states, "Several components of this library
have been accepted into the C++ standard technical report." I'm wondering
whether that ought to be removed as well. If anyone has thoughts about that
as far is whether it should be removed as well, please let me know.

Thanks

On Thu, Jan 28, 2016 at 4:18 AM, Paul A. Bristow <pbristow_at_[hidden]>
wrote:

> > -----Original Message-----
> > From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Nathan
> Wilson
> > Sent: 28 January 2016 04:42
> > To: boost_at_[hidden]
> > Subject: [boost] [Iterator] [PR] Fix for documentation #8010
> >
> > Hi,
> >
> > As a followup to my inquiry about maintaining the Iterator Library about
> a month back, I wanted to
> > create PR for a simple documentation fix.
> >
> > So, here it is:
> > https://github.com/boostorg/iterator/pull/21
> >
> > Please let me know if there are any thoughts and/or if I'm doing
> something incorrectly.
>
> This reminds me that some time ago I undertook to look at refactoring the
> iterator library
> documentation.
>
> I did start on this job, but other tasks gained priority.  I've looked
> again at the progress that I
> made with this and concluded that it was far too much effort to justify
> the gains in usefulness to
> users.
>
> The work involved adding a lot of Doxygen-syntax documentation as comments
> in the header files -
> something that should be done at the time of writing the code, not as an
> afterthought.  Once this is
> done, different tools can be used to process this and produce stuff for
> users to read, and find
> using search tools and indexes. It is easy and not too tedious when
> writing the code, but very
> tedious and much more difficult if you leave it until later.
>
> So revising the iterator docs is a 'don't start from here' task :-(
>
> Let this be a warning to those who don't like the look of a particular
> tool and suffer from NIH and
> create their own particular documentation format and toolchain!
>
> Paul
>
> PS  I am waiting for the next Clang 3.8 release before looking at how the
> compiler processes
> Doxygen-syntax comments and investigating how it could better document the
> template-infested Boost
> code, something the current Doxygen Parser doesn't do well (considering
> that it isn't a compiler it
> is amazing that it does anything at all with Boosty templated code).  It
> may then be time to revisit
> the whole overcomplicated toolchain.
>
>
> ---
> Paul A. Bristow
> Prizet Farmhouse
> Kendal UK LA8 8AB
> [phone]
>
>
>
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>