João Abecasis wrote:
Hi!
Eric Niebler wrote:
Usually names in the detail:: namespace are replaced by "unspecified"
automatically by doxygen2boostbook.xsl. But not when a public type
inherits from a type in the detail namespace. Then, the ugly
implementation detail shows up in the generated docs.
The following patch completely hides bases that are in the detail
namespace. (I thought that would be better than showing inheritance
from "unspecified".)
OK to commit?
FWIW, I think it makes sense to hide implementation details, and that
includes inheriting from classes in the detail namespace. I reviewed the
patch and it looks good to me (didn't try it, though).
My only (albeit very small) concern is whether it affects other
libraries, notably other Boost libraries. I won't hold this point by
itself against the patch and wouldn't think twice if there are
reasonable workarounds to get the current behaviour.
I should also point out that types in the detail namespace are culled by
doxygen2boostbook. So without the patch, a class foo that inherits from
detail::foo_impl will be documented as such, but there will be no docs
for detail::foo_impl. I can't imagine a Boost library is depending on
this behavior.
The "workaround" -- that is, if the inheritance relationship is not an
implementation detail and needs to be documented -- is to move foo_impl
out of the detail namespace. That makes sense because in that case, it's
not a detail.
Having posted patches to BoostBook myself very recently and in the past,
however, I have to ask: Who is maintaining BoostBook and who should be
bugged before committing patches?
We're all in this together. :-)
When it comes to obvious bugs the understanding is to just fix them.
What about enhancements and general evolution of the tool? Is it alright
to assume that unless there are strong objections to the patches (and of
course I'm assuming we're all reasonable people ;-) it is ok to commit
them?
That's reasonable. As the original author of the XSL transforms, I value
Doug Gregor's feedback, but since he's a busy guy, I haven't let the
lack of Doug's (or anybody else's) feedback stop me in past.
FWIW, I received private email from Doug in support of this particular
patch.
--
Eric Niebler
Boost Consulting
www.boost-consulting.com
-------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc. Do you grep through log files
for problems? Stop! Download the new AJAX search engine that makes
searching your log files as easy as surfing the web. DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
