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
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Nathan Wilson Sent: 28 January 2016 04:42 To: boost@lists.boost.org 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 +44 (0) 1539 561830
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost