From d34dea05f8e9af3e85c45067bad9990c0040946d Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Tue, 15 Nov 2022 11:34:46 +0000 Subject: [PATCH] libstdc++: Document use of Markdown for Doxygen comments libstdc++-v3/ChangeLog: * doc/xml/manual/documentation_hacking.xml: Document use of Markdown for Doxygen comments. Tweak formatting. * doc/html/manual/documentation_hacking.html: Regenerate. --- .../html/manual/documentation_hacking.html | 21 ++++++++------ .../doc/xml/manual/documentation_hacking.xml | 28 ++++++++++++++----- 2 files changed, 34 insertions(+), 15 deletions(-) diff --git a/libstdc++-v3/doc/html/manual/documentation_hacking.html b/libstdc++-v3/doc/html/manual/documentation_hacking.html index c978d5f3d1f..bd44b61010d 100644 --- a/libstdc++-v3/doc/html/manual/documentation_hacking.html +++ b/libstdc++-v3/doc/html/manual/documentation_hacking.html @@ -135,7 +135,9 @@ formatting system, and will require the expansion of TeX's memory capacity. Specifically, the pool_size variable in the configuration file texmf.cnf may - need to be increased by a minimum factor of two. + need to be increased by a minimum factor of two. Alternatively, using + LATEX_CMD=lualatex might allow the docs to be + build without running out of memory.

Generating the Doxygen Files

The following Makefile rules run Doxygen to generate HTML docs, XML docs, XML docs as a single file, PDF docs, and the @@ -269,9 +271,12 @@ purpose. See stl_iterator.h for a good example of the “other” kind of grouping.

- Please use markup tags like @p and @a when referring to things - such as the names of function parameters. Use @e for emphasis - when necessary. Use @c to refer to other standard names. + Markdown can be used for formatting text. Doxygen is configured to + support this, and it is a good compromise between readable comments + in the C++ source and nice formatting in the generated HTML. + Please format the names of function parameters in either code font + or italics. Use underscores or @e for emphasis when necessary. + Use backticks or @c to refer to other standard names. (Examples of all these abound in the present code.)

Complicated math functions should use the multi-line format. @@ -322,8 +327,8 @@ writing Doxygen comments. Single and double quotes, and separators in filenames are two common trouble spots. When in doubt, consult the following table. -

Table B.2. HTML to Doxygen Markup Comparison

HTMLDoxygen
\\\
"\"
'\'
<i>@a word
<b>@b word
<code>@c word
<em>@a word
<em><em>two words or more</em>

Docbook

Prerequisites

Table B.3. Docbook Prerequisites

ToolVersionRequired By
docbook5-style-xsl1.76.1all
xsltproc1.1.26all
xmllint2.7.7validation
dblatex0.3pdf output
pdflatex2007-59pdf output
docbook2X0.8.8info output
epub3 stylesheetsb3epub output

- Editing the DocBook sources requires an XML editor. Many +

Table B.2. HTML to Doxygen Markup Comparison

HTMLDoxygenMarkdown
\\\\\
"\"\"
'\'\'
<i>@a word_word_ or *word*
<b>@b word**word** or __word__
<code>@c word`word`
<em>@a word_word_ or *word*
<em><em>two words or more</em>_two words or more_

Docbook

Prerequisites

Table B.3. Docbook Prerequisites

ToolVersionRequired By
docbook5-style-xsl1.76.1all
xsltproc1.1.26all
xmllint2.7.7validation
dblatex0.3pdf output
pdflatex2007-59pdf output
docbook2X0.8.8info output
epub3 stylesheetsb3epub output

+ An XML editor is recommended for editing the DocBook sources. Many exist: some notable options include emacs, Kate, or Conglomerate. @@ -386,8 +391,8 @@ build directory, based on the output format. For instance, the HTML docs will be in doc/docbook/html.

- The 

doc-html-docbook-regenerate

target will generate - the HTML files and copy them back to the libstdc++ source tree. + The doc-html-docbook-regenerate target will + generate the HTML files and copy them back to the libstdc++ source tree. This can be used to update the HTML files that are checked in to version control.

diff --git a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml index 776d5e857b5..44672f6e26d 100644 --- a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml +++ b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml @@ -286,7 +286,9 @@ formatting system, and will require the expansion of TeX's memory capacity. Specifically, the pool_size variable in the configuration file texmf.cnf may - need to be increased by a minimum factor of two. + need to be increased by a minimum factor of two. Alternatively, using + LATEX_CMD=lualatex might allow the docs to be + build without running out of memory. @@ -515,9 +517,12 @@ - Please use markup tags like @p and @a when referring to things - such as the names of function parameters. Use @e for emphasis - when necessary. Use @c to refer to other standard names. + Markdown can be used for formatting text. Doxygen is configured to + support this, and it is a good compromise between readable comments + in the C++ source and nice formatting in the generated HTML. + Please format the names of function parameters in either code font + or italics. Use underscores or @e for emphasis when necessary. + Use backticks or @c to refer to other standard names. (Examples of all these abound in the present code.) @@ -595,6 +600,7 @@ HTML Doxygen + Markdown @@ -602,41 +608,49 @@ \ \\ + \\ " \" + \" ' \' + \' <i> @a word + _word_ or *word* <b> @b word + **word** or __word__ <code> @c word + `word` <em> @a word + _word_ or *word* <em> <em>two words or more</em> + _two words or more_ @@ -719,7 +733,7 @@ - Editing the DocBook sources requires an XML editor. Many + An XML editor is recommended for editing the DocBook sources. Many exist: some notable options include emacs, Kate, or Conglomerate. @@ -815,8 +829,8 @@ - The doc-html-docbook-regenerate target will generate - the HTML files and copy them back to the libstdc++ source tree. + The doc-html-docbook-regenerate target will + generate the HTML files and copy them back to the libstdc++ source tree. This can be used to update the HTML files that are checked in to version control.