Merge branch 'master' of github.com:doxygen/doxygen

Author: doxygen

doc/customize.dox

@@ -142,11 +142,11 @@ This will create 3 files:
   contains a couple of commands of the form \$word. These will be replaced
   by Doxygen on the fly.
 - footer.html is a HTML fragment which Doxygen normally uses to end
-  a HTML page. Also here special commands can be used. This file contain the
+  a HTML page. Also here special commands can be used. This file contains the
   link to www.doxygen.org and the body and html end tags.
 - customdoxygen.css is the default cascading style sheet
   used by Doxygen. It is recommended only to look into this file and overrule
-  some settings you like by putting them in a separate stylesheets and
+  some settings you like by putting them in a separate stylesheet and
   referencing those extra files
   via \ref cfg_html_extra_stylesheet "HTML_EXTRA_STYLESHEET".
 
@@ -155,8 +155,8 @@ You should edit these files and then reference them from the configuration file.
 - \ref cfg_html_footer "HTML_FOOTER" = \c footer.html
 - \ref cfg_html_extra_stylesheet "HTML_EXTRA_STYLESHEET" = \c my_customdoxygen.css
 
-\note it is not longer recommended to use \ref cfg_html_stylesheet "HTML_STYLESHEET",
-as it make it difficult to upgrade to a newer version of Doxygen. Use
+\note it is no longer recommended to use \ref cfg_html_stylesheet "HTML_STYLESHEET",
+as it makes it difficult to upgrade to a newer version of Doxygen. Use
 \ref cfg_html_extra_stylesheet "HTML_EXTRA_STYLESHEET" instead.
 
 See the documentation of the \ref cfg_html_header "HTML_HEADER" tag
@@ -168,7 +168,7 @@ it as a source file. Doxygen will copy it for you.
 
 \note If you use images or other external content in a custom header you
 need to make sure these end up in the HTML output directory yourself,
-for instance by writing a script that runs Doxygen can then copies the
+for instance by writing a script that runs Doxygen and then copies the
 images to the output.
 
 \warning The structure of headers and footers may change after upgrading to
@@ -201,7 +201,7 @@ LAYOUT_FILE = DoxygenLayout.xml
 \endverbatim
 To change the layout all you need to do is edit the layout file.
 
-The toplevel structure of the file looks as follows:
+The top-level structure of the file looks as follows:
 \verbatim
 <doxygenlayout version="1.0">
   <navindex>
@@ -261,7 +261,7 @@ www.google.com:
   </navindex>
 \endverbatim
 
-The url field can also be a relative URL. If the URL starts with \@ref
+The URL field can also be a relative URL. If the URL starts with \@ref
 the link will point to a documented entities, such as a class, a function,
 a group, or a related page. Suppose we have defined a page using \@page with
 label mypage, then a tab with label "My Page" to this page would look

doc/diagrams.dox

@@ -24,7 +24,7 @@
   cross-platform graph drawing toolkit and can be found 
   at https://www.graphviz.org/
 
-  If you have the "dot" tool in the path, you can set
+  If you have the "dot" tool in the PATH (environment variable), you can set
   \ref cfg_have_dot "HAVE_DOT" to \c YES in the configuration file to 
   let Doxygen use it.
 
@@ -82,7 +82,7 @@
   <li> A \b yellow box indicates a class. A box can have a 
        little marker in the lower right corner to indicate that the class 
        contains base classes that are hidden. 
-       For the class diagrams the maximum tree width is currently 8 elements. 
+       For the class diagrams, the maximum tree width is currently 8 elements.
        If a tree is wider some nodes will be hidden.
        If the box is filled with a 
        dashed pattern the inheritance relation is virtual.
@@ -122,7 +122,7 @@
        include dependency graph) or public inheritance (for the other graphs).
   <li> A <b>dark green</b> arrow indicates protected inheritance.
   <li> A <b>dark red</b> arrow indicates private inheritance.
-  <li> A <b>purple dashed</b> arrow indicated a "usage" relation, the 
+  <li> A <b>purple dashed</b> arrow indicates a "usage" relation, the
        edge of the arrow is labeled with the variable(s) responsible for the
        relation.
        Class \c A uses class \c B, if class \c A has a member variable \c m 

doc/docblocks.dox

@@ -46,7 +46,7 @@ the concatenation of all comment blocks found within the body of the method or f
 Having more than one brief or detailed description is allowed (but not recommended,
 as the order in which the descriptions will appear is not specified).
 
-As the name suggest, a brief description is
+As the name suggests, a brief description is
 a short one-liner, whereas the detailed description provides longer,
 more detailed documentation. An "in body" description can also act as a detailed
 description or can describe a collection of implementation details.
@@ -221,7 +221,7 @@ on the order in which Doxygen parses the code.
 Unlike most other documentation systems, Doxygen also allows you to put
 the documentation of members (including global functions) in front of
 the \e definition. This way the documentation can be placed in the source
-file instead of the header file. This keeps the header file compact, and allows the
+file instead of the header file. This keeps the header file compact and allows the
 implementer of the members more direct access to the documentation.
 As a compromise the brief description could be placed before the
 declaration and the detailed description before the member definition.
@@ -326,7 +326,7 @@ for the Qt style.
 By default a Javadoc style documentation block behaves the same way as a
 Qt style documentation block. This is not according the Javadoc specification
 however, where the first sentence of the documentation block is automatically
-treated as a brief description. To enable this behavior you should set
+treated as a brief description. To enable this behavior, you should set
 \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to YES in the configuration
 file. If you enable this option and want to put a dot in the middle of a
 sentence without ending it, you should put a backslash and a space after it.
@@ -353,7 +353,7 @@ block to automatically be treated as a brief description, one may set
 
 \subsubsection structuralcommands Documentation at other places
 
-In the examples in the previous section the comment blocks were always located *in
+In the examples in the previous section, the comment blocks were always located *in
 front* of the declaration or definition of a file, class or namespace or *in
 front* or *after* one of its members.
 Although this is often comfortable, there may sometimes be reasons to put the
@@ -433,16 +433,16 @@ using structural commands:
  documentation. The disadvantage of this approach is that prototypes are
  duplicated, so all changes have to be made twice! Because of this you
  should first consider if this is really needed, and avoid structural
- commands if possible. I often receive examples that contain \\fn command
- in comment blocks which are place in front of a function. This is clearly
+ commands if possible. I often receive examples that contain the \\fn command
+ in comment blocks which are placed in front of a function. This is clearly
  a case where the \\fn command is redundant and will only lead to problems.
 
  When you place a comment block in a file with one of the following extensions
  `.dox`, `.txt`, `.doc`, `.md` or `.markdown` or when the extension maps to
  `md` by means of the \ref cfg_extension_mapping "EXTENSION_MAPPING"
  then Doxygen will hide this file from the file list.
 
- If you have a file that Doxygen cannot parse but still would like to document it,
+ If you have a file that Doxygen cannot parse but you still would like to document it,
  you can show it as-is using \ref cmdverbinclude "\\verbinclude", e.g.
 
 \verbatim
@@ -481,7 +481,7 @@ documentation instead of <tt>\"\"\"</tt> use <tt>\"\"\"!</tt> or set
 \note Instead of <tt>\"\"\"</tt> one can also use <tt>'''</tt>.
 
 There is also another way to document Python code using comments that
-start with "##" or "##<". These type of comment blocks are more in line with the
+start with "##" or "##<". These types of comment blocks are more in line with the
 way documentation blocks work for the other languages supported by Doxygen
 and this also allows the use of special commands.
 
@@ -497,14 +497,14 @@ Here is the same example again but now using Doxygen style comments:
  for the corresponding \mbox{\LaTeX} documentation that is generated by Doxygen.
  \endlatexonly
 
-Since python looks more like Java than like C or C++, you should set
+Since Python looks more like Java than like C or C++, you should set
 \ref cfg_optimize_output_java "OPTIMIZE_OUTPUT_JAVA" to \c YES in the
 configuration file.
 
 
 \subsection vhdlblocks Comment blocks in VHDL
 
-For VHDL a comment normally start with "--". Doxygen will extract comments
+For VHDL a comment normally starts with "--". Doxygen will extract comments
 starting with "--!". There are only two types of comment blocks in VHDL;
 a one line "--!" comment representing a brief description, and a multi-line
 "--!" comment (where the "--!" prefix is repeated for each line) representing
@@ -526,15 +526,15 @@ Here is an example VHDL file with Doxygen comments:
  for the corresponding \mbox{\LaTeX} documentation that is generated by Doxygen.
  \endlatexonly
 
-As of VHDL 2008 it is also possible to use `/``*` style comments.<br>
+As of VHDL 2008, it is also possible to use `/``*` style comments.<br>
 Doxygen will handle `/``* ... *``/`as plain comments and `/``*! ... *``/`
 style comments as special comments to be parsed by Doxygen.
 
 To get proper looking output you need to set
 \ref cfg_optimize_output_vhdl "OPTIMIZE_OUTPUT_VHDL" to \c YES in the
 configuration file. This will also affect a number of other settings. When they
 were not already set correctly Doxygen will produce a warning telling which
-settings where overruled.
+settings were overruled.
 
 \subsection fortranblocks Comment blocks in Fortran
 
@@ -614,7 +614,7 @@ forms of additional markup on top of Markdown formatting.
    as specified in the <a href="http://standards.iso.org/ittf/PubliclyAvailableStandards/c042926_ISO_IEC_23270_2006(E).zip">C# standard</a>.
    See \ref xmlcmds for the XML commands supported by Doxygen.
 
-If this is still not enough Doxygen also supports a \ref htmlcmds "subset" of
+If this is still not enough, Doxygen also supports a \ref htmlcmds "subset" of
 the <a href="https://en.wikipedia.org/wiki/HTML">HTML</a> markup language.
 
 \htmlonly

doc/doxygen.1

@@ -3,42 +3,43 @@
 Doxygen \- documentation system for various programming languages
 .SH DESCRIPTION
 Doxygen is a documentation system for C++, C, Java, Objective-C, IDL
-(Corba and Microsoft flavors), Fortran, Python, VHDL and to some extent PHP, C#, and D.
+(CORBA and Microsoft flavors), Fortran, Python, VHDL and to some extent PHP, C#, and D.
 .PP
-You can use Doxygen in a number of ways:
+You can use Doxygen in several ways:
 .TP
-1) Use Doxygen to generate a template configuration file*:
+1) Generate a template configuration file*:
 .IP
 doxygen [-s] \fB\-g\fR [configName]
 .TP
-2) Use Doxygen to update an old configuration file*:
+2) Update an existing configuration file*:
 .IP
 doxygen [-s] \fB\-u\fR [configName]
 .TP
-3) Use Doxygen to generate documentation using an existing configuration file*:
+3) Generate documentation using an existing configuration file*:
 .IP
 doxygen [configName]
 .TP
-4) Use Doxygen to generate a template file controlling the layout of the generated documentation:
+4) Generate a template file that controls the layout of the generated documentation:
 .IP
 doxygen \fB\-l\fR [layoutFileName]
 .IP
 .RS 0
-   In case layoutFileName is omitted DoxygenLayout.xml will be used as filename.
-   If - is used for layoutFileName Doxygen will write to standard output.
+   If layoutFileName is omitted, DoxygenLayout.xml will be used as the filename.
+   If - is used for layoutFileName, Doxygen writes to standard output.
 .RE
 .TP
-5) Use Doxygen to generate a template style sheet file for RTF, HTML or Latex.
+5) Generate a template style sheet file for RTF, HTML or LaTeX:
 .IP
 RTF:
 doxygen \fB\-w\fR rtf styleSheetFile
 .IP
 HTML:
 doxygen \fB\-w\fR html headerFile footerFile styleSheetFile [configFile]
 .IP
-LaTeX: doxygen \fB\-w\fR latex headerFile footerFile styleSheetFile [configFile]
+LaTeX:
+doxygen \fB\-w\fR latex headerFile footerFile styleSheetFile [configFile]
 .TP
-6) Use Doxygen to generate an rtf extensions file
+6) Generate an RTF extensions file:
 .IP
 RTF:
 doxygen \fB\-e\fR rtf extensionsFile
@@ -47,18 +48,18 @@ doxygen \fB\-e\fR rtf extensionsFile
    If - is used for extensionsFile Doxygen will write to standard output.
 .RE
 .TP
-7) Use Doxygen to compare the used configuration file with the template configuration file
+7) Compare the used configuration file with the template configuration file:
 .IP
 doxygen \fB\-x\fR [configFile]
 .TP
-   Use Doxygen to compare the used configuration file with the template configuration file
+   Compare the used configuration file with the template configuration file
 .RS 0
-   without replacing the environment variables or CMake type replacement variables
+   without replacing the environment variables or CMake type replacement variables:
 .RE
 .IP
 doxygen \fB\-x_noenv\fR [configFile]
 .TP
-8) Use Doxygen to show a list of built-in emojis.
+8) Show a list of built-in emojis.
 .IP
 doxygen \fB\-f\fR emoji outputFileName
 .IP
@@ -67,9 +68,9 @@ doxygen \fB\-f\fR emoji outputFileName
 .RE
 .PP
 .RS 0
-*) If \fB\-s\fR is specified the comments of the configuration items in the config file will be omitted.
-   If configName is omitted 'Doxyfile' will be used as a default.
-   If - is used for configFile Doxygen will write / read the configuration to /from standard output / input.
+*) If \fB\-s\fR is specified, the comments of the configuration items in the config file will be omitted.
+   If configName is omitted, 'Doxyfile' will be used by default.
+   If - is used for configFile, Doxygen will write / read the configuration to / from standard output / input.
 .RE
 .PP
 If \fB\-q\fR is used for a Doxygen documentation run, Doxygen will see this as if QUIET=YES has been set.

doc/doxyindexer.1

@@ -11,7 +11,7 @@ doxysearch.cgi as a CGI program to search the data indexed by doxyindexer.
 .SH OPTIONS
 .TP
 \fB\-o\fR <output_dir>
-The directory where to write the doxysearch.db to. 
-If omitted the current directory is used.
+The directory where doxysearch.db will be written.
+If omitted, the current directory is used.
 .SH SEE ALSO
 doxygen(1), doxysearch(1), doxywizard(1).

doc/doxysearch.1

@@ -1,11 +1,10 @@
 .TH DOXYSEARCH "1" "@DATE@" "doxysearch.cgi @VERSION@" "User Commands"
 .SH NAME
-doxysearch.cgi \- search engine used for searching in doxygen documentation.
+doxysearch.cgi \- search engine for Doxygen documentation
 .SH SYNOPSIS
 .B doxysearch.cgi
 .SH DESCRIPTION
-CGI binary that is used by doxygen generated HTML output to search for words. 
-The tool uses the search index called \fBdoxysearch.db\fR produced by 
-doxyindexer. 
+CGI binary used by Doxygen-generated HTML output to search for words.
+The tool uses the search index \fBdoxysearch.db\fR produced by doxyindexer.
 .SH SEE ALSO
 doxygen(1), doxyindexer(1), doxywizard(1).

doc/emojisup.dox

@@ -16,9 +16,9 @@
  */
 /*! \page emojisup Emoji support
 
-The [Unicode consortium](http://www.unicode.org/) has defined a set of
+The [Unicode Consortium](http://www.unicode.org/) has defined a set of
 [emoji](https://en.wikipedia.org/wiki/Emoji) with the corresponding Unicode
-sequences. Doxygen supports the subset of emoji characters as used by GitHub (based on the list
+sequences. Doxygen supports the subset of emoji characters used by GitHub (based on the list
 https://api.github.com/emojis).
 An emoji is created using the \ref cmdemoji "\\emoji" command.
 For example `\emoji smile` or `\emoji :smile:` both produce \emoji smile.
@@ -39,7 +39,7 @@ For the different Doxygen output types there is an output defined:
 
 \section emojiimage Emoji image retrieval
 
-In the list of images can be downloaded via the following Python script:
+In the list, images can be downloaded via the following Python script:
 \code{.py}
 # script to download the emoticons from GitHub and to produce a table for
 # inclusion in Doxygen. Works with python 2.7+ and python 3.x
@@ -115,10 +115,10 @@ if __name__=="__main__":
 \endcode
 
 When invoking the script with the `-d image_dir` option,
-the images will by downloaded to the `image_dir` directory.
+the images will be downloaded to the `image_dir` directory.
 
 When invoking the script with the `-s` option,
-no progress messages are shown while fetching the images, except for when fetching an image fails.
+no progress messages are shown while fetching the images, except when fetching an image fails.
 
 By means of the Doxygen configuration parameter
 \ref cfg_latex_emoji_directory "LATEX_EMOJI_DIRECTORY" the requested directory can be selected.

doc/faq.dox

@@ -136,7 +136,7 @@ in the documentation of the class MyClassName regardless of the name of the actu
 header file in which the definition of MyClassName is contained.
 
 If you want Doxygen to show that the include file should be included using
-quotes instead of angle brackets you should type:
+quotes instead of angle brackets, you should type:
 \verbatim
 /*! \class MyClassName myhdr.h "path/myhdr.h"
  *
@@ -308,7 +308,7 @@ so I started to write my own tool...
 
 When redirecting all the console output of Doxygen, i.e. messages and warnings, this can be interleaved or
 in a non-expected order.
-The, technical, reason for this is that the `stdout` can be buffered.
+The technical reason for this is that the `stdout` can be buffered.
 It is possible to overcome this by means of the `-b` of Doxygen, like e.g `doxygen -b > out.txt 2>&1`.
 Note this might cost a little more time though.
 

doc/install.dox

@@ -21,7 +21,7 @@
 
 First go to the
 <a href="https://www.doxygen.org/download.html">download</a> page
-to get the latest distribution, if you have not downloaded Doxygen already.
+to get the latest distribution if you have not downloaded Doxygen already.
 
 \section install_src_unix Compiling from source on UNIX
 
@@ -37,7 +37,7 @@ following to build the executable:
     \addindex python
 <li>You need \c python (version 2.7 or higher, see https://www.python.org).
 <li>In order to generate a \c Makefile for your platform, you need
-    <a href="https://cmake.org/">cmake</a> version 3.14 or later.
+    <a href="https://cmake.org/">Cmake</a> version 3.14 or later.
     \addindex cmake
 </ul>
 
@@ -46,7 +46,7 @@ tools should be installed.
 
 <ul>
 <li>Qt Software's GUI toolkit
-    <a href="https://doc.qt.io/">Qt</A>
+    <a href="https://doc.qt.io/">Qt</a>
     \addindex Qt
     version 5.14 or higher (including Qt 6).
     This is needed to build the GUI front-end Doxywizard.
@@ -68,11 +68,11 @@ tools should be installed.
 
 For testing at least these additional dependencies should be available:
 <ul>
-<li>xmllint (libxml2-ultils)</li>
+<li>xmllint (libxml2-utils)</li>
 <li>bibtex (texlive-binaries)</li>
 </ul>
 
-Compilation is now done by performing the following steps:
+Compilation steps:
 
 <ol>
 <li>Unpack the archive, unless you already have done that: