Doxygen emits C++ alias templates ("template<...> using X = ...;") as
typedef memberdefs carrying a templateparamlist, but the conversion
dropped that list, so alias templates appeared as plain typedefs with
their template parameters lost.
- doxygen2boostbook.xsl: carry the templateparamlist through to a
<template> child of the generated <typedef>.
- boostbook.dtd: allow an optional <template> inside <typedef>.
- type.xsl: when a typedef has a <template> child, render it as
"template<...> using name = type;" and exclude it from typedef
column alignment.
A reference whose name is root-qualified with a leading :: (e.g. ::boost::container::allocator_traits) is never resolved, producing a spurious:
Cannot find class named '::boost::container::allocator_traits'
warning when generating the documentation.
The commit strips a leading :: in "generate-cxx-links". when present, requires an exact match (empty qualifiers) . Relative-name resolution is unchanged.
* Ported setup_boostbook.py to Python 3.
* Updated DocBook XSL to 1.79.2, DocBook DTD to 4.5.
* Switched DocBook XSL to "nons" version, which is compatible with DocBook 4.x.
The "ns" version is compatible with DocBook 5 and produces incorrect output
in some cases. See the discussion in https://github.com/boostorg/boostbook/pull/13
for more details.
* Updated download URLs to the actual ones.
* Added checking checksums for the downloaded packages to ensure authenticity.
* Added creating backup of user-config.jam before modification.
* user-config.jam modification now preserves location of the rules
that the script modifies.
* The script now produces absolute paths in user-config.jam.
Since setup_boostbook.py now implements everything from setup_boostbook.sh
and is (presumably) more portable, removed setup_boostbook.sh to avoid
code duplication.
Closes https://github.com/boostorg/boostbook/pull/19.
Doxygen generates extra spaces in some function return types (e.g. involving
a const reference) and template parameter defaults (in partucular, when
the default is formatted across multiple lines in the C++ source).
Normalize spaces in those cases.
When there are multiple \throws entries in a function documentation, the second
and further exception names were omitted from output and a combined description
was associated with the first exception. Fix this by producing separate
paragraphs, one per exception.
Additionally, support free form exception description when the exception type
is specified as "~". In this case, the exception name is not used, and the
entry description is used to initialize the paragraph in the output.
Updated test to verify these changes.
This makes the entries after "See Also:" to be displayed inline rather
than starting from the next line. This is consistent with other kinds
of paragraphs generated from Doxygen output.
Sorted parameters are more difficult to read, as you normally expect
the parameters to be described in the order they are listed in the
function signature. This also breaks parameter grouping when adjacent
parameters are related (e.g. a pair of iterators).
Instead of Doxygen-synthesized names like "@0", either omit the name
entirely, when the enum name is not a link to a separate definition,
or display "[unnamed]" placeholder for the name that serves as a link.
Similar to other contexts, replace default types and values in template
parameter lists that mention implementation details, as configured in
boost.doxygen.detail parameter, with "unspecified".
This fixes dangling refs to implementation detail types and values that
were removed from BoostBook output but are still mentioned in template
parameter defaults.
When Doxygen option INLINE_INHERITED_MEMB=YES is used, Doxygen generates
duplicate class member definitions with the same ids, when the member is
inherited from a base class. This results in duplicate ids in BoostBook output
and the corresponding errors.
Work around this by checking if the member id starts with the id of the
enclosing class. If it does then the member is assumed to be a genuine member
of the class and we generate a Doxygen id for it. Doxygen refs will point to
this definition of the member. If the member id is different then it must be
an inherited member, and we don't generate a Doxygen id for it. BoostBook
stylesheets will generate a unique id for it, which will be used to link
synopsis to reference of the member in the derived class' documentation.
\parblock can be used to group multiple paragraps under a block command
that expects a single paragraph as argument (e.g. \returns). So just
forward the contents of the parblock in the current context.
Produce id attributes for all entities generated by Doxygen. For refs,
generate link tags referencing those ids. Preface the ids with "doxygen."
prefix to avoid potential clashes with ids that may be present in other
places of the resulting DocBook document. Also add the document refid to
the prefix to avoid potential clashes between multiple Doxygen-generated
documents with SHORT_NAMES=YES.
In order to pass through the generated ids without modification (to keep
links working in the output), change generate.id template so that it
returns the value of the id attribute, if one is present, instead of
generating a new id.
The end result is that all references generated by Doxygen (to methods,
classes, variables and so on) propagate to the final HTML output instead
of being stripped during Doxygen to BoostBook translation.
Comparing formatted XML files makes the comparison less sensitive
to whitespace and newline differences between XML documents, and
also makes the subsequent diff more informative, if any differences
are found.
Previously, class members and free functions in sectiondef with
kind="user-defined" would be stripped from HTML output, making function
grouping effectively non-functional. This commit fixes this by converting
such sectiondefs to either method-group or free-function-group in BoostBook
output, depending on whether the grouping is within a class or namespace.
Additionally, previously constructors, destructors and assignment operators
were not allowed to be inside method-groups, which were another reason for
these members to be stripped from the output. This commit allows these members
in member-groups and modifies DTD accordingly.
Also, this fixes duplicate constructors, destructors and assignment operators
generated after the sections for public, private and protected member
functions. This was due to applying XSL templates twice - once when generating
method-group, and then after the method-group.
This commit adds a new XSL parameter boost.sort.params, which allows
users to disable alphabetical sorting of the function and template
parameters in detailed descriptions of functions and classes. By
default, sorting is enabled, which maintains the previous behavior.
Sorting is disabled when the parameter is set to 0. In this case,
parameters are listed in the order they are listed in the BoostBook
documentation, which is normally the same as they are listed in the
function signature or template preamble.
Doxygen 1.9.1 generates enum <initializer> tags with text starting with
an equal sign ('=') followed by the enum value initializer. This sign
was copied under the BoostBook <default> tag, and BoostBook styleseets
add an equal sign of their own when converting this tag to HTML. This
resulted in duplicate equal signs in the HTML output.
This commit strips the leading equal sign from the initializer before
putting it into the <default> tag.
Ion Gaztañaga