[Boost-commit] svn:boost r71500 - sandbox/guild/mylibrary/libs/mylibrary/doc

Subject: [Boost-commit] svn:boost r71500 - sandbox/guild/mylibrary/libs/mylibrary/doc
From: pbristow_at_[hidden]
Date: 2011-04-26 07:55:32

Author: pbristow
Date: 2011-04-26 07:55:30 EDT (Tue, 26 Apr 2011)
New Revision: 71500
URL: http://svn.boost.org/trac/boost/changeset/71500

Log:
Added some PREDEFINED examples (and some minor edits).
Binary files modified: 
   sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.pdf
Text files modified: 
   sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2    |    63 ++++++++++++++++++++++++++++++++++----- 
   sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk |    11 +++---                                  
   2 files changed, 61 insertions(+), 13 deletions(-)

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2	2011-04-26 07:55:30 EDT (Tue, 26 Apr 2011)
@@ -55,17 +55,60 @@
       [ glob ../../../boost/mylibrary/*.hpp ]
       [ glob ../../../boost/mylibrary/detail/*.hpp ] #  More include files, if necessary to include headers in /details.
    :
+   # Pass some setting parameters to Doxygen.
                         <doxygen:param>WARNINGS=YES # Default NO, but useful to see warnings, especially in a logfile.
                         # It is also wise to to set a warnings logfile like this:
                         <doxygen:param>WARN_LOGFILE=AutoDoxywarnings.log # This may not be empty (usually not a good sign!), depending on options chosen.
                         # Much better to send message to a logfile than the default stderr.
                         # and make sure that there are no Doxygen errors or significant warnings in the log file.
-			<doxygen:param>RECURSIVE=NO # Search recursively down subdirectories.
-      <doxygen:param>EXTRACT_ALL=NO
-			<doxygen:param>HIDE_UNDOC_MEMBERS=YES
-			<doxygen:param>EXTRACT_PRIVATE=NO
-			<doxygen:param>EXPAND_ONLY_PREDEF=YES
-			<xsl:param>"boost.doxygen.reftitle=Boost.mylibrary C++ Reference"
+			<doxygen:param>RECURSIVE=NO # Search recursively down .hpp and .cpp subdirectories.
+      <doxygen:param>EXTRACT_ALL=NO 
+			<doxygen:param>EXTRACT_PRIVATE=NO # NO means do not extract info about private member functions and data. 
+			<doxygen:param>HIDE_UNDOC_MEMBERS=YES # Only show members that have some documentation like \param, \return ...
+			<doxygen:param>MACRO_EXPANSION=YES # YES will expand all macro names in the source code (default = NO).
+			<doxygen:param>EXPAND_ONLY_PREDEF=YES # 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.
+			# If EXPAND_ONLY_PREDEF tag can be used to specify a list of macro names that should be expanded (as defined).
+			# The PREDEFINED tag can be used to specify one or more macro names that are defined 
+			# before the preprocessor is started (similar to the -D option of gcc).
+			# The argument of the tag is a list of macros of the form:
+			#    name or name=definition (no spaces).
+			# If the definition and the "=" are omitted, "=1" is assumed.
+			# To prevent a macro definition from being undefined via #undef or
+			# recursively expanded use the := operator instead of the = operator.
+			# See http://www.stack.nl/~dimitri/doxygen/config.html#cfg_predefined.
+			# static char *malloc BOOST_PREVENT_MACRO_SUBSTITUTION(const size_type bytes);
+			# will not produce a helpful Doxygen output, so
+			# replace some with more helpful text, or none, for example:
+			<doxygen:param>"PREDEFINED= \\
+				 \"BOOST_PREVENT_MACRO_SUBSTITUTION\" \\
+				 \"BOOST_STATIC_CONSTANT(T,V)=static x const y\" \\
+				 \"BOOST_UNITS_AUTO_STATIC_CONSTANT(a,b)=static const auto a = b\" \\
+				 \"BOOST_DEDUCED_TYPENAME=typename\" \\
+				 \"BOOST_CONSTEXPR=constexpr\" \\
+				 \"BOOST_UNITS_TYPEOF(a)=typeof(a)\" \\
+				 \"BOOST_UNITS_HAS_TYPEOF=1\" \\
+				 \"BOOST_MPL_ASSERT(expr)=\" \\
+				 \"BOOST_ASSERT(expr)=\" \\
+				 \"ASSERT(x)=assert(x)\" \\
+				 \"__cplusplus \""
+      # BOOST_PREVENT_MACRO_SUBSTITUTION,  will not be replaced by ,
+      # BOOST_STATIC_CONSTANT will be replaced by "static x const y",
+      # BOOST_DEDUCED_TYPENAME will be replaced by "typename",
+      # BOOST_CONSTEXPR will be replaced by "constexpr".
+      
+      # The syntax hoops to jump through are 'interesting' for more than one PREDEFINED,
+      # and to permit spaces within definitions (use double quotes).
+      # Don't forget that every double quote " needs a preceeding \trip character!
+      # and that each trailing continuation \ needs a preceeding \trip character too!
+      # And finally that if more than one item is included (as here) the whole is
+      # enclosed in "PREDEFINED=... ", but without a leading \.  Go figure...
+      
+      # A grep for PREDEFINED= in jamfiles will reveal even more complex examples.
+      # Boost Libraries with useful examples are: Accumulators, Interprocess, MPI, Random, Units, Expressive.
+      
+      # Optionally, you can provide a Reference section name specific for your library, for example:
+			<xsl:param>"boost.doxygen.reftitle=Boost.Mylibrary C++ Reference"
    ;
 
 
@@ -164,6 +207,7 @@
                 <dependency>css-install
                 <dependency>png-install
                 <dependency>svg-install
+		
    ;
 
 # Install (copy) the 'master' copy of boostbook Cascading Style sheet from your current Boost-root.
@@ -177,9 +221,12 @@
 install svg-install : [ glob $(boost-root)/doc/src/images/*.svg ] : <location>html/images ;
 
 # install pdf-install : standalone : <install-type>PDF <location>. ;
-# Effectively copies the file from \bin folder to the \doc folder.
-# But will not work as expected if doxygen and/or autoindex is used
+# Effectively copies the file from \bin folder to the \doc folder,
+# but will not work as expected if doxygen and/or autoindex is used
 # because a modified pdf file is created, so 
 # this command  will rename the file to the expected filename, here mylibrary.pdf.
 
 install pdf-install : standalone : <install-type>PDF <location>. <name>mylibrary.pdf ;
+
+install html-install : standalone : <location>. ;
+

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.pdf
==============================================================================
Binary files. No diff available.

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk	2011-04-26 07:55:30 EDT (Tue, 26 Apr 2011)
@@ -25,7 +25,7 @@
 [def __boost [@http://www.boost.org/ Boost]] [/Boost.org]
 [def __boostroot [@boost: Boost root]] [/ Your boost root]
 [/Note the custom boost root url schema for linking to files within the Boost distribution.]
-[/Note It can't be used for images.]
+[/Note It can't be used for images, nor for pdf, so not so useful.]
 [/def __boostlicense [@http://www.boost.org/LICENSE_1_0.txt Boost License]]
 [/ Or refer to your most recent version of Boost.]
 [def __boostlicense [@boost:/LICENSE_1_0.txt Boost License]]
@@ -109,10 +109,9 @@
   both in __quickbook automatically added reference section,
   and also in __doxygen standalone documentation.
 
-* Automatic indexing to __doxygen -generated entities
+* Automatic indexing to __doxygen generated entities
   (namespaces, classes, functions, typedefs).
-  and author-chosen indexing of text
-  see __autoindex.
+  and author-chosen indexing of text, see __autoindex.
 
 * Macro system for simple text substitution.
 
@@ -164,7 +163,7 @@
 Users get great benefit from an *index* of nearly all documentation, however short.
 The only downside is that total size of documentation can be much increased by the index.
 Since space is not usually an issue, hyperlinking (in both html and pdf)
-makes the size increase not a significant disadvantage.
+makes the size increase an insignificant disadvantage.
 
 A C++ Reference section, using __doxygen
 (and __doxygen comments in the C++ code
@@ -246,6 +245,8 @@
 
 [tip This should appear on the pdf version 
 (but may be redundant on a html version where the last edit date is on the first (home) page).]
+
+[warning Home page "Last revised" is GMT, not local time.  Last edit date is local time.]
 [/See also Adobe Reader pdf File Properties for creation date, and PDF producer, version and page count.]
 
 [endsect] [/section:version_id Version Info]