[thread][1.35.0][trunk] New thread documentation
Hi, I've just checked in some new quickbook-based documentation for the much-revised thread library on trunk. I expect there's still some parts that are inadequate, but given the major changes since Boost 1.34, I want to ensure that the new docs are in with the new release. So, first question: is it OK to commit the new documentation to the release branch? Second question: I see that many libraries have the generated documentation checked in to SVN. Is this recommended practice? Next: The thread library documentation index at BOOST_ROOT/libs/thread/doc/index.html redirects to BOOST_ROOT/doc/html/thread.html, which in turn redirects to the generated version on the website. Is this still appropriate? Finally: Are there any glaring omissions that I ought to address before 1.35.0 is shipped? Thanks, Anthony -- Anthony Williams Just Software Solutions Ltd - http://www.justsoftwaresolutions.co.uk Registered in England, Company Number 5478976. Registered Office: 15 Carrallack Mews, St Just, Cornwall, TR19 7UL
Anthony Williams wrote:
Hi,
I've just checked in some new quickbook-based documentation for the much-revised thread library on trunk. I expect there's still some parts that are inadequate, but given the major changes since Boost 1.34, I want to ensure that the new docs are in with the new release.
So, first question: is it OK to commit the new documentation to the release branch?
IMO this should be part of the release - I assume the existing docs are outdated - verging on downright misleading at present? But check with Beman on this one.
Second question: I see that many libraries have the generated documentation checked in to SVN. Is this recommended practice?
Not as such... but if the libraries documentation has grown too complex and/or needs it's own XSLT options setting when generating to make it navigable, then yes by all means.
Next: The thread library documentation index at BOOST_ROOT/libs/thread/doc/index.html redirects to BOOST_ROOT/doc/html/thread.html, which in turn redirects to the generated version on the website. Is this still appropriate?
Yes, if you're going to building the docs as part of the stuff in /doc/, but not if you're checking in the generated docs.
Finally: Are there any glaring omissions that I ought to address before 1.35.0 is shipped?
No idea :-) John.
John Maddock wrote:
Anthony Williams wrote:
Hi,
I've just checked in some new quickbook-based documentation for the much-revised thread library on trunk. I expect there's still some parts that are inadequate, but given the major changes since Boost 1.34, I want to ensure that the new docs are in with the new release.
So, first question: is it OK to commit the new documentation to the release branch?
IMO this should be part of the release - I assume the existing docs are outdated - verging on downright misleading at present? But check with Beman on this one.
Yes, go ahead.
Second question: I see that many libraries have the generated documentation checked in to SVN. Is this recommended practice?
Not as such... but if the libraries documentation has grown too complex and/or needs it's own XSLT options setting when generating to make it navigable, then yes by all means.
I'd prefer you didn't for the 1.35.0 release.
Next: The thread library documentation index at BOOST_ROOT/libs/thread/doc/index.html redirects to BOOST_ROOT/doc/html/thread.html, which in turn redirects to the generated version on the website. Is this still appropriate?
Yes, if you're going to building the docs as part of the stuff in /doc/, but not if you're checking in the generated docs.
I agree with John.
Finally: Are there any glaring omissions that I ought to address before 1.35.0 is shipped?
No idea :-)
Me either :-) --Beman
Beman Dawes <bdawes <at> acm.org> writes:
John Maddock wrote:
Anthony Williams wrote:
Hi,
I've just checked in some new quickbook-based documentation for the much-revised thread library on trunk. I expect there's still some parts that are inadequate, but given the major changes since Boost 1.34, I want to ensure that the new docs are in with the new release.
So, first question: is it OK to commit the new documentation to the release branch?
Yes, go ahead.
Thanks. Committed as revision 43674.
Second question: I see that many libraries have the generated documentation checked in to SVN. Is this recommended practice?
Not as such... but if the libraries documentation has grown too complex and/or needs it's own XSLT options setting when generating to make it navigable, then yes by all means.
I'd prefer you didn't for the 1.35.0 release.
OK. Thanks again, Anthony -- Anthony Williams Just Software Solutions Ltd - http://www.justsoftwaresolutions.co.uk Registered in England, Company Number 5478976. Registered Office: 15 Carrallack Mews, St Just, Cornwall, TR19 7UL
participants (3)
-
Anthony Williams -
Beman Dawes -
John Maddock