doxygen doc / STL container unit test
I have two questions regarding boost library development: 1. this page: http://www.boost.org/doc/libs/1_35_0/doc/html/boostbook/getting/started.html explains how to set up the boost documentation system and write BoostBooks. what I find missing is how to generate the typical boost class synposis with doxygen. I also can't find doxygen configuration files or anything of that sort in the boost tree. how do you go about integrating automatically generated documentation into a BoostBook? 2. boost implements quite a few STL containers. is there a unit test that can test my STL container for conformity? say, I have a container that models the concept of a std::list, I'd like to change a typedef to my type, run the test and know that it behaves like advertised. Does anything like that already exist? thank you
2009/9/11 Stefan Strasser <strasser@uni-bremen.de>:
I have two questions regarding boost library development:
1. this page: http://www.boost.org/doc/libs/1_35_0/doc/html/boostbook/getting/started.html
explains how to set up the boost documentation system and write BoostBooks. what I find missing is how to generate the typical boost class synposis with doxygen. I also can't find doxygen configuration files or anything of that sort in the boost tree. how do you go about integrating automatically generated documentation into a BoostBook?
I had the same problem when I started my quickbook docs a couple of months ago. May be the documentation is incomplete at this point or a few links could be helpful to find the docs about doxygen integration, if they already exist elsewhere. The good thing about boost is ... it's open source ;-) So I browsed the doc directories of other recent quickbook documented libraries and copied their code: You have to code the required information in two files for a library somelib: Jamfile.v2 and somelib.qbk. These files should both be located in <boost_root>/libs/somelib/doc # ---------------------------------------------------------- # Jamfile.v2 import doxygen ; import quickbook ; # ---------------------------------------------------------- # Doxygen doxygen somelibdoc : [ glob ../../../boost/somelib/*.hpp ] : <doxygen:param>EXTRACT_ALL=YES <doxygen:param>HIDE_UNDOC_MEMBERS=NO <doxygen:param>EXTRACT_PRIVATE=NO <doxygen:param>ENABLE_PREPROCESSING=YES <doxygen:param>MACRO_EXPANSION=NO <doxygen:param>EXPAND_ONLY_PREDEF=YES <doxygen:param>SEARCH_INCLUDES=NO <reftitle>"My fancy new Library Reference" ; # ---------------------------------------------------------- # Quickbook import quickbook ; xml somelib : somelib.qbk ; boostbook standalone : somelib : <xsl:param>boost.root=../../../.. <xsl:param>boost.libraries=../../../libraries.htm <xsl:param>toc.max.depth=2 <xsl:param>toc.section.depth=2 <xsl:param>chunk.section.depth=2 <dependency>somelibdoc ; # ---------------------------------------------------------- In the file that is your library's quickbook root: somelib.qbk you have to include the doxygen generated reference to your docs by [xinclude somelibdoc.xml] HTH Joachim
thanks for that, my doc builds now. I have 2 problems left though: 1. inline documentation that looks like: \throw A Here's why A was thrown \throw B Here's why B was thrown is translated to Throws: A in the output. no mention of B, and no explanations. this works with standalone doxygen. is there any way to change that without changing any of the stuff that is used for every boost library? 2. doxygen keeps ignoring my parameters. my Jamfile.v2 looks exactly like yours below, I copied it from boost.intrusive and changed it. but private and undocumented members still show up in the output. any hint on what could be the reason for that? thanks again Am Friday 11 September 2009 16:52:46 schrieb Joachim Faulhaber:
You have to code the required information in two files for a library somelib: Jamfile.v2 and somelib.qbk. These files should both be located in <boost_root>/libs/somelib/doc
# ---------------------------------------------------------- # Jamfile.v2 import doxygen ; import quickbook ;
# ---------------------------------------------------------- # Doxygen
doxygen somelibdoc
[ glob ../../../boost/somelib/*.hpp ]
<doxygen:param>EXTRACT_ALL=YES <doxygen:param>HIDE_UNDOC_MEMBERS=NO <doxygen:param>EXTRACT_PRIVATE=NO <doxygen:param>ENABLE_PREPROCESSING=YES <doxygen:param>MACRO_EXPANSION=NO <doxygen:param>EXPAND_ONLY_PREDEF=YES <doxygen:param>SEARCH_INCLUDES=NO <reftitle>"My fancy new Library Reference" ; # ---------------------------------------------------------- # Quickbook
import quickbook ;
xml somelib
somelib.qbk ;
boostbook standalone
somelib
<xsl:param>boost.root=../../../.. <xsl:param>boost.libraries=../../../libraries.htm <xsl:param>toc.max.depth=2 <xsl:param>toc.section.depth=2 <xsl:param>chunk.section.depth=2 <dependency>somelibdoc ; # ----------------------------------------------------------
In the file that is your library's quickbook root: somelib.qbk you have to include the doxygen generated reference to your docs by
[xinclude somelibdoc.xml]
HTH Joachim _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Stefan Strasser Sent: Tuesday, September 15, 2009 11:50 PM To: boost@lists.boost.org Subject: Re: [boost] doxygen doc / STL container unit test
2. doxygen keeps ignoring my parameters. my Jamfile.v2 looks exactly like yours below, I copied it from boost.intrusive and changed it. but private and undocumented members still show up in the output. any hint on what could be the reason for that?
I also find (for the SVG Plot docs) that not all the doxygen parameters seem to have the desired effect (though seem to). I have yet to look into this properly. Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
Am Wednesday 16 September 2009 13:07:53 schrieb Paul A. Bristow:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On
Behalf Of
Stefan Strasser Sent: Tuesday, September 15, 2009 11:50 PM To: boost@lists.boost.org Subject: Re: [boost] doxygen doc / STL container unit test
2. doxygen keeps ignoring my parameters. my Jamfile.v2 looks exactly like yours below, I copied it from boost.intrusive and changed it. but private and undocumented members still show up in the output. any hint on what could be the reason for that?
I also find (for the SVG Plot docs) that not all the doxygen parameters seem to have the desired effect (though seem to).
the parameters in the jamfile do end up in the doxygen configuration file, but it seems that doxygen ignores a lot of parameters for its XML output, like hide undoc members. which makes sense, because a XML processor can take care of that. but it doesn't, so two libraries I've looked at encapsulate all private declarations in /// @cond ... /// @endcond tags.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Stefan Strasser Sent: Wednesday, September 16, 2009 4:48 PM To: boost@lists.boost.org Subject: Re: [boost] doxygen doc / STL container unit test
doxygen keeps ignoring my parameters. my Jamfile.v2 looks exactly like yours below, I copied it from boost.intrusive and changed it. but private and undocumented members still show up in the output. any hint on what could be the reason for that?
I also find (for the SVG Plot docs) that not all the doxygen parameters seem to have the desired effect (though some seem to).
the parameters in the jamfile do end up in the doxygen configuration file, but it seems that doxygen ignores a lot of parameters for its XML output, like hide undoc members. which makes sense, because a XML processor can take care of that. but it doesn't, so two libraries I've looked at encapsulate all private declarations in /// @cond ... /// @endcond tags.
Groan - I have tons of private stuff and I'd really rather not have to do this! But thanks for this info. Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
At 5:48 PM +0200 9/16/09, Stefan Strasser wrote:
the parameters in the jamfile do end up in the doxygen configuration file, but it seems that doxygen ignores a lot of parameters for its XML output, like hide undoc members. which makes sense, because a XML processor can take care of that. but it doesn't, so two libraries I've looked at encapsulate all private declarations in /// @cond ... /// @endcond tags.
In case this hasn't already been checked, is doxygen's EXTRACT_PRIVATE parameter set to NO?
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Kim Barrett Sent: Wednesday, September 16, 2009 4:20 PM To: boost@lists.boost.org Subject: Re: [boost] doxygen doc / STL container unit test
At 5:48 PM +0200 9/16/09, Stefan Strasser wrote:
the parameters in the jamfile do end up in the doxygen configuration file, but it seems that doxygen ignores a lot of parameters for its XML output, like hide undoc members. which makes sense, because a XML processor can take care of that. but it doesn't, so two libraries I've looked at encapsulate all private declarations in /// @cond ... /// @endcond tags.
In case this hasn't already been checked, is doxygen's EXTRACT_PRIVATE parameter set to NO?
I believe so: (but I haven't tried fiddling with other settings yet). Suggestions? Paul doxygen autodoc : [ glob ../../../boost/svg_plot/*.hpp ] [ glob ../../../boost/svg_plot/detail/*.hpp ] : #<doxygen:param>INPUT="filename1 directoryname2" # Separate with spaces. # But also see paths specified above. <doxygen:param>RECURSIVE=YES # Search subdirectories as well. <doxygen:param>STRIP_FROM_PATH=I:/ # Strip this from full path name. <doxygen:param>TAB_SIZE=2 # <doxygen:param>EXTRACT_ALL=YES # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in # documentation are documented, even if no documentation was available. # Private class members and static file members will be hidden unless # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES <doxygen:param>HIDE_UNDOC_MEMBERS=NO <doxygen:param>INLINE_INHERITED_MEMB=YES # Show all inherited members of a class in the documentation of that class as if those members were ordinary class members. <doxygen:param>SORT_MEMBER_DOCS=YES <doxygen:param>EXTRACT_STATIC=YES # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. <doxygen:param>EXTRACT_PRIVATE=NO # If the EXTRACT_PRIVATE tag is set to YES all private members of a class will be included in the documentation # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. # <doxygen:param>EXTRACT_LOCAL_STATIC=YES # ? Not supported. <doxygen:param>EXTRACT_LOCAL_METHODS=YES # Only useful for Objective C? <doxygen:param>EXTRACT_LOCAL_CLASSES=YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. # If set to NO only classes defined in header files are included. <doxygen:param>ENABLE_PREPROCESSING=YES # Doxygen will expand all macro names in the source code. <doxygen:param>MACRO_EXPANSION=YES # If the MACRO_EXPANSION tag is set to YES all macro # Doxygen will expand all names in the source code. <doxygen:param>EXPAND_ONLY_PREDEF=NO # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. <doxygen:param>SEARCH_INCLUDES=YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files in the INCLUDE_PATH. <doxygen:param>INLINE_INFO=YES # If the INLINE_INFO tag is set to YES (the default) then a tag [inline] is inserted in the documentation for inline members. <doxygen:param>SORT_BRIEF_DOCS=YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief descriptions of file, namespace and class members alphabetically by member name. <doxygen:param>SORT_MEMBER_DOCS=YES # If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen will sort the (detailed) documentation of file and class members alphabetically by member name. <doxygen:param>SHOW_INCLUDE_FILES=YES # List of the files that are included by a file in the documentation of that file. <doxygen:param>REPEAT_BRIEF=YES # Prepend the brief description of a member or function before the detailed description <doxygen:param>BRIEF_MEMBER_DESC=YES # Include brief member descriptions after the members that are listed in the file and class <doxygen:param>MULTILINE_CPP_IS_BRIEF=YES # Treat a multi-line C++ special comment block (i.e. a block of //! or /// comments) as a brief description. # May be best to always use \brief and \details to avoid ambiguity? <doxygen:param>INCLUDE_PATH=$(BOOST_ROOT) # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by the preprocessor. <doxygen:param>WARNINGS=YES # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings for undocumented members. # If EXTRACT_ALL is set to YES then this flag will automatically be disabled. <doxygen:param>WARN_IF_UNDOCUMENTED=YES # If WARN_IF_UNDOCUMENTED is set to YES, # then doxygen will generate warnings for undocumented members. <doxygen:param>WARN_IF_DOC_ERROR=YES # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for # potential errors in the documentation. <doxygen:param>WARN_LOGFILE=../../../libs/svg_plot/doc/doxywarnings.log # Specific log file - ideally this should be empty! <doxygen:param>EXCLUDE="../../../boost/svg_plot/svg_fwd.hpp ../../../boost/svg_plot/stylesheet.hpp" # Exclude to avoid warnings about file(s) undocumented. # Note: no commas required but need quotes if more than one file. ; #<doxygen:param>"PREDEFINED=\"BOOST_DEDUCED_TYPENAME=typename\" " # See Doxygen configuration for detailed explanation of these options
Am Wednesday 16 September 2009 17:20:21 schrieb Kim Barrett:
At 5:48 PM +0200 9/16/09, Stefan Strasser wrote:
the parameters in the jamfile do end up in the doxygen configuration file, but it seems that doxygen ignores a lot of parameters for its XML output, like hide undoc members. which makes sense, because a XML processor can take care of that. but it doesn't, so two libraries I've looked at encapsulate all private declarations in /// @cond ... /// @endcond tags.
In case this hasn't already been checked, is doxygen's EXTRACT_PRIVATE parameter set to NO?
yes, the doxygen parameters must be right, because I enabled doxygen html output and the html came out alright. but as I've said above, doxygen seems to export all elements to XML and the boost XSLT translation doesn't seem to care about "private".
2009/9/11 Stefan Strasser <strasser@uni-bremen.de>:
I have two questions regarding boost library development:
2. boost implements quite a few STL containers. is there a unit test that can test my STL container for conformity? say, I have a container that models the concept of a std::list, I'd like to change a typedef to my type, run the test and know that it behaves like advertised. Does anything like that already exist?
This question is definitely a good one. Because it immediately reveals two important points about testing: (1) Tests should be reusable (2) Tests should be structured along concepts as concepts are composable and refinable, also the concept tests should be composable and refinable. I did not research if there are efforts at boost to support such kind of concept based testing. But I think the usefulness of such a framework is obvious. Along with the development of my own library I wrote a test tool that implements a law based testing which might be interesting in this respect. I called the tool a 'Law Based Test Automaton' (LaBatea). It is a generic tool that allows to define Laws (also known as axioms ala c++0x or semantical requirements or semantical invariants), to generate law instances and to report law violations, if such violations are found. A concept to be tested can be defined as a set of laws. Once a law or a set of laws is defined, it can be validated for a given type. There is one additional requirement though: A generator that randomly generates test data has to be implemented for every type to be validated. As already mentioned I developed LaBatea as a test tool for the Interval Template Library. The first application of the tool to code other than my own was Lukes boost.polygon. The tool certainly has some shortcomings at the present state though. (1) The system of date generators should be more decoupled. (2) Running large sets of laws (concepts) with different instance types for their template parameters -- which is the final goal -- leads to test programs that do compile quite slowly. If you are interested in LaBatea you find the code at https://svn.boost.org/svn/boost/sandbox/itl/boost/validate/ https://svn.boost.org/svn/boost/sandbox/itl/libs/validate/ I am sorry there is virtually no documentation on LaBatea. But the latest example on boost.polygon contains some helpful comments. https://svn.boost.org/svn/boost/sandbox/itl/libs/validate/example/labat_poly... LaBatea compiles fastest on msvc-9. I also tested successfully with gcc-4.3.2. LaBatea does not compile with gcc-4.1.0 and older. Cheers Joachim
This question is definitely a good one. Because it
immediately reveals two important points about testing:
(1) Tests should be reusable (2) Tests should be structured along concepts
as concepts are composable and refinable, also the concept tests should be composable and refinable.
I did not research if there are efforts at boost to support such kind of concept based testing. But I think the usefulness of such a framework is obvious.
I committed something similar for the BGL test suite (test_graph.cpp, I think in trunk). It's not nearly as formal and primarily just exercises the Graph concept interfaces. Mostly it's just a framework for sanity testing a graph adaptor or data structure. Also virtually no documentation. One of the things that I found was that generically testing data structures requires a fairly complete set of type traits and metafunctions that query types based on their concepts. I'm using these to extensively tag dispatch some of the test methods. It seems like a good approach, but it's not easy to write. Andrew Sutton andrew.n.sutton@gmail.com
participants (5)
-
Andrew Sutton -
Joachim Faulhaber -
Kim Barrett -
Paul A. Bristow -
Stefan Strasser