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

Subject: Re: [boost] [Iterator] [PR] Fix for documentation #8010
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-01-28 05:18:03

> -----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]