├── test
├── files
│ ├── plain.h
│ ├── sub
│ │ └── other2.h
│ ├── plain.h.faceup
│ ├── example.h
│ ├── other.h
│ ├── other.h.faceup
│ ├── inline.h
│ ├── inline.h.faceup
│ ├── example.h.faceup
│ ├── verbatim.h
│ ├── sections.h
│ ├── known-problems.h
│ ├── emphasis.h
│ ├── verbatim.h.faceup
│ ├── code.h
│ ├── markdown.h
│ ├── sections.h.faceup
│ ├── known-problems.h.faceup
│ ├── code.h.faceup
│ ├── normal.h
│ ├── markdown.h.faceup
│ └── normal.h.faceup
├── highlight-doxygen-test-setup.el
├── highlight-doxygen-test-files.el
└── highlight-doxygen-test-basic.el
├── README.md
└── highlight-doxygen.el
/test/files/plain.h:
--------------------------------------------------------------------------------
1 | //! This is a plain doxygen comment.
2 |
--------------------------------------------------------------------------------
/test/files/sub/other2.h:
--------------------------------------------------------------------------------
1 | // This file is placed in a subdirectory and is referred to from "normal.h"
2 |
--------------------------------------------------------------------------------
/test/files/plain.h.faceup:
--------------------------------------------------------------------------------
1 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a plain doxygen comment.
2 | »»
--------------------------------------------------------------------------------
/test/files/example.h:
--------------------------------------------------------------------------------
1 | //! \file
2 | //! \brief Example Doxygen file demonstrating highlight-doxygen.el
3 |
4 | //! This function does something.
5 | //!
6 | //! \a a_value the first value
7 | //! \a another_value the second value
8 | //!
9 | //! Example:
10 | //!
11 | //! \code
12 | //! {
13 | //! int this_is_a_value = ...;
14 | //! while (MyFunction(this_is_a_value, 2))
15 | //! {
16 | //! // do something
17 | //! }
18 | //! }
19 | //! \endcode
20 |
21 | void MyFunction(int a_value, int another_value);
22 |
--------------------------------------------------------------------------------
/test/files/other.h:
--------------------------------------------------------------------------------
1 | // other.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // This file is referred to from "normal.h".
27 |
28 | // Code:
29 |
30 | // other.h ends here.
31 |
--------------------------------------------------------------------------------
/test/files/other.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:other.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:This file is referred to from "normal.h".
27 | »
28 | «m:// »«x:Code:
29 | »
30 | «m:// »«x:other.h ends here.
31 | »
--------------------------------------------------------------------------------
/test/files/inline.h:
--------------------------------------------------------------------------------
1 | // inline.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // Example C++ code with Doxygen comments containing "inline" constructs.
27 |
28 | // Code:
29 |
30 | //! A function my_func() is highlighted.
31 | //!
32 | //! A qualified function my_class::my_func() is highlighted.
33 | //!
34 | //! A qualified function my_class#my_func() is highlighted.
35 |
36 | class TestInline
37 | {
38 | };
39 |
40 | // inline.h ends here
41 |
--------------------------------------------------------------------------------
/test/files/inline.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:inline.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:Example C++ code with Doxygen comments containing "inline" constructs.
27 | »
28 | «m:// »«x:Code:
29 | »
30 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! A function «f:my_func»() is highlighted.
31 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
32 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! A qualified function «t:my_class»::«f:my_func»() is highlighted.
33 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
34 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! A qualified function «t:my_class»#«f:my_func»() is highlighted.
35 | »»
36 | «k:class» «t:TestInline»
37 | {
38 | };
39 |
40 | «m:// »«x:inline.h ends here
41 | »
--------------------------------------------------------------------------------
/test/highlight-doxygen-test-setup.el:
--------------------------------------------------------------------------------
1 | ;;; highlight-doxygen-test-setup.el --- Setup and execute all tests.
2 |
3 | ;; Copyright (C) 2018 Anders Lindgren
4 |
5 | ;; Author: Anders Lindgren
6 |
7 | ;; This file is part of the `highlight-doxygen' package.
8 |
9 | ;; This program is free software; you can redistribute it and/or modify
10 | ;; it under the terms of the GNU General Public License as published by
11 | ;; the Free Software Foundation, either version 3 of the License, or
12 | ;; (at your option) any later version.
13 |
14 | ;; This program is distributed in the hope that it will be useful,
15 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 | ;; GNU General Public License for more details.
18 |
19 | ;; You should have received a copy of the GNU General Public License
20 | ;; along with this program. If not, see .
21 |
22 | ;;; Commentary:
23 |
24 | ;; This package sets up a suitable enviroment for testing
25 | ;; `highlight-doxygen', and executes the tests.
26 | ;;
27 | ;; Usage:
28 | ;;
29 | ;; emacs -q -l highlight-doxygen-test-setup.el
30 | ;;
31 | ;; Note that this package assumes that some packages are located in
32 | ;; specific locations.
33 |
34 | ;;; Code:
35 |
36 | (setq inhibit-startup-screen t)
37 | (prefer-coding-system 'utf-8)
38 |
39 | (defvar highlight-doxygen-test-setup-directory
40 | (if load-file-name
41 | (file-name-directory load-file-name)
42 | default-directory))
43 |
44 | (dolist (dir '("." ".." "../../faceup"))
45 | (add-to-list 'load-path (concat highlight-doxygen-test-setup-directory dir)))
46 |
47 | (require 'highlight-doxygen)
48 | (require 'highlight-doxygen-test-basic)
49 | (require 'highlight-doxygen-test-files)
50 |
51 | (if noninteractive
52 | (ert-run-tests-batch t)
53 | (ert t))
54 |
55 | ;;; highlight-doxygen-test-setup.el ends here
56 |
--------------------------------------------------------------------------------
/test/files/example.h.faceup:
--------------------------------------------------------------------------------
1 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:file»
2 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:brief» Example Doxygen file demonstrating highlight-doxygen.el
3 | »»«:highlight-doxygen-comment:
4 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This function does something.
5 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
6 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:a» «:highlight-doxygen-variable:a_value» the first value
7 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:a» «:highlight-doxygen-variable:another_value» the second value
8 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
9 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Example:
10 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
11 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
12 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
13 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «t:int» «v:this_is_a_value» = ...;
14 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «k:while» (MyFunction(this_is_a_value, 2))
15 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: {
16 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «:highlight-doxygen-code-block:// do something»
17 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: }
18 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
19 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
20 | »»
21 | «t:void» «f:MyFunction»(«t:int» «v:a_value», «t:int» «v:another_value»);
22 |
--------------------------------------------------------------------------------
/test/files/verbatim.h:
--------------------------------------------------------------------------------
1 | // verbatim.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // Example C++ code with Doxygen "verbatim" blocks.
27 |
28 | // Code:
29 |
30 | // Note: It appears as though "verbatim" can't stretch across C++
31 | // comments. Also, it emits formatting like leading asterisks.
32 | //
33 | // In most cases, a "\code" block or a MarkDown-style verbatim is
34 | // perferred.
35 |
36 | //! This comment contains a "verbatim" block.
37 | //!
38 | //! \verbatim
39 | //! This is verbatim
40 | //! \endverbatim
41 | //!
42 | //! More comments.
43 |
44 | class TestVerbatimKeywordCpp
45 | {
46 | };
47 |
48 |
49 | /*! This comment contains a "verbatim" block.
50 | *
51 | * The following will contain the " *":s in the output.
52 | *
53 | * \verbatim
54 | * This is verbatim
55 | * \endverbatim
56 | *
57 | * More comments.
58 | *
59 | * \verbatim
60 | This is also verbatim
61 | \endverbatim
62 | *
63 | */
64 |
65 | class TestVerbatimKeywordC
66 | {
67 | };
68 |
69 | //! This comment contains a "verbatim" block.
70 | //!
71 | //! Note: When Doxygen renders the following paragraph, it is split
72 | //! into three separate paragraphs, hence this isn't a good way to
73 | //! write inline code snippets.
74 | //!
75 | //! The following \verbatim is verbatim \endverbatim but this isn't.
76 | //!
77 | //! More comments.
78 |
79 | class TestVerbatimKeywordOneLine
80 | {
81 | };
82 |
83 | // verbatim.h ends here
84 |
--------------------------------------------------------------------------------
/test/files/sections.h:
--------------------------------------------------------------------------------
1 | // sections.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // This file contains Doxygen commands for writing sections and pages.
27 |
28 | // Code:
29 |
30 | //! \mainpage This is the title of the documentation
31 | //!
32 | //! This is the body text of the main page.
33 | //!
34 | //! \section sec1 This is the first section
35 | //!
36 | //! This is the body text of the first section.
37 | //!
38 | //! \par This is a paragraph title
39 | //! Paragraph body.
40 | //!
41 | //! \vhdlflow This is VHDL diagram title
42 | //! Paragraph body. (This only work in VHDL...)
43 | //!
44 | //! \section sec2 This is the second section
45 | //!
46 | //! This is the body text of the second section.
47 | //!
48 | //! \subsection sub21 This is a subsection
49 | //!
50 | //! This is the body text of the subsection.
51 | //!
52 | //! In \ref sec1 and \ref par211 you can read more.
53 | //!
54 | //! \subsubsection sub211 This is a subsubsection
55 | //!
56 | //! This is the body text of the subsubsection.
57 | //!
58 | //! \paragraph par211 This is a paragraph in the subsubsection
59 | //!
60 | //! This is the body of the paragraph.
61 | //!
62 | //! And more text (wonder where this will go).
63 | //!
64 | //! \page page1 This is a page
65 | //!
66 | //! Without quotes.
67 | //!
68 | //! \page page2 "This is another page"
69 | //!
70 | //! With quotes. (Incorrectly formed for Doxygen)
71 | //!
72 | //! \subpage subpage1 This is a subpage
73 | //!
74 | //! Without quotes. (Incorrectly formed for Doxygen)
75 | //!
76 | //! \subpage subpage2 "This is another page"
77 | //!
78 | //! With quotes.
79 | //!
80 | //! \subpage subpage3
81 | //!
82 | //! Without title.
83 | //!
84 | //! And even more text (wonder where this will go).
85 |
86 | // sections.h ends here
87 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # highlight-doxygen - Highlight Doxygen comments
2 |
3 | *Author:* Anders Lindgren
4 | *Version:* 0.0.2
5 | *URL:* [https://github.com/Lindydancer/highlight-doxygen](https://github.com/Lindydancer/highlight-doxygen)
6 |
7 | Advanced highlighting package for Doxygen comments.
8 |
9 | In addition to highlighting Doxygen commands and their arguments,
10 | entire Doxygen comment are highlighted, making them stand out
11 | compared to other comments. In addition, and code blocks are
12 | highlighted according to the language they are written in.
13 |
14 | ## Usage
15 |
16 | This package provide two minor modes, `highlight-doxygen-mode` and
17 | `highlight-doxygen-global-mode`.
18 |
19 | Can enable `highlight-doxygen-mode` from the hook of a mode.
20 |
21 | Alternatively, you can enable the minor mode for all major modes
22 | specified in `highlight-doxygen-modes`. Typically, this is done by
23 | placing the following in a suitable init file:
24 |
25 | (highlight-doxygen-global-mode 1)
26 |
27 | ## What is highlighted
28 |
29 | * The full Doxygen comment is highlighted with a different
30 | background color, to make them stand out compared to normal code
31 | other comments.
32 | * Doxygen commands and their arguments are highlighted. The
33 | arguments are highlighted according to the signature of the
34 | commands. For example, the argument to the `\a` command is
35 | highlighted as a variable.
36 | * Code blocks are highlighted using the Emacs highlighting rules
37 | for the language they are written in. In addition, the
38 | background is changed to make the code block stand out.
39 | * Customization friendly. This package define a number of custom
40 | faces that can be customized to fine tune the appearance if this
41 | package. The default value of all defined faces inherit from
42 | standard Emacs faces, which mean that customizations done by the
43 | user or themes are automatically used.
44 |
45 | ## Code blocks
46 |
47 | A code block is specified using a pair of Doxygen commands like
48 | `\code` and `\endcode` or `\dot` and `\enddot`.
49 |
50 | Code blocks are syntax highlighted using the major mode they are
51 | written in. The major mode is selected as follows:
52 |
53 | * If the `\code{.ext}` construct is used, the major mode associated
54 | with extension `.ext` is used.
55 | * For `\dot`, `\msc`, and `\startuml` is used, the extensions
56 | `.dot`, `.msc`, and `.plantuml` are used, respectively.
57 | * For `\code` blocks that does not specify an extension, the major
58 | mode of the buffer is used.
59 |
60 |
61 | ---
62 | Converted from `highlight-doxygen.el` by [*el2markdown*](https://github.com/Lindydancer/el2markdown).
63 |
--------------------------------------------------------------------------------
/test/highlight-doxygen-test-files.el:
--------------------------------------------------------------------------------
1 | ;;; highlight-doxygen-test-files.el --- Regression test for highlight-doxygen.
2 |
3 | ;; Copyright (C) 2016 Anders Lindgren
4 |
5 | ;; Author: Anders Lindgren
6 | ;; Package-Requires: ((faceup "0.0.4"))
7 |
8 | ;; This file is part of the `highlight-doxygen' package.
9 |
10 | ;; This program is free software: you can redistribute it and/or modify
11 | ;; it under the terms of the GNU General Public License as published by
12 | ;; the Free Software Foundation, either version 3 of the License, or
13 | ;; (at your option) any later version.
14 |
15 | ;; This program is distributed in the hope that it will be useful,
16 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 | ;; GNU General Public License for more details.
19 |
20 | ;; You should have received a copy of the GNU General Public License
21 | ;; along with this program. If not, see .
22 |
23 | ;;; Commentary:
24 |
25 | ;; Regression test of `highlight-doxygen', a package providing
26 | ;; font-lock rules for doxygen comment. This module verifies
27 | ;; fontification of a number of files. This is done by keeing a text
28 | ;; representation of the fontification using `faceup' markup, in
29 | ;; addition to the original files.
30 | ;;
31 | ;; The actual check is performed using `ert', with font-lock test
32 | ;; function provided by `faceup'.
33 |
34 | ;;; Code:
35 |
36 | (require 'faceup)
37 |
38 | (defvar highlight-doxygen-test-dir (faceup-this-file-directory))
39 |
40 | (defun highlight-doxygen-test-file (file)
41 | "Test that FILE is fontified as the .faceup file describes.
42 |
43 | FILE is interpreted as relative to this source directory."
44 | (faceup-test-font-lock-file '(c++-mode
45 | highlight-doxygen-mode)
46 | (concat
47 | highlight-doxygen-test-dir
48 | file)))
49 | (faceup-defexplainer highlight-doxygen-test-file)
50 |
51 |
52 | (ert-deftest highlight-doxygen-test-files ()
53 | (should (highlight-doxygen-test-file "files/code.h"))
54 | (should (highlight-doxygen-test-file "files/example.h"))
55 | (should (highlight-doxygen-test-file "files/inline.h"))
56 | (should (highlight-doxygen-test-file "files/known-problems.h"))
57 | (should (highlight-doxygen-test-file "files/markdown.h"))
58 | (should (highlight-doxygen-test-file "files/normal.h"))
59 | (should (highlight-doxygen-test-file "files/other.h"))
60 | (should (highlight-doxygen-test-file "files/plain.h"))
61 | (should (highlight-doxygen-test-file "files/sections.h"))
62 | (should (highlight-doxygen-test-file "files/verbatim.h")))
63 |
64 | (provide 'highlight-doxygen-test-files)
65 |
66 | ;; highlight-doxygen-test-files.el ends here.
67 |
--------------------------------------------------------------------------------
/test/files/known-problems.h:
--------------------------------------------------------------------------------
1 | // known-problems.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // Example C++ code with Doxygen comments demonstrates a number of
27 | // known problems with the `highlight-doxygen' package.
28 |
29 | // Code:
30 |
31 | //! Doxygen comments with known problems.
32 | class TestKnownProblemsClass
33 | {
34 | public:
35 | /*! This is a C-style block.
36 | The package can't highlight the following empty line as the rest
37 | of the block, because there are no characters on it to highlight.
38 |
39 | */
40 | void TestCStyleBlocksWithEmptyLines();
41 |
42 | /*! \brief Some text
43 | * \namespace FakeKnownProblemNamespace
44 | *
45 | * This and the next comment should be highlighted as separate
46 | * comment blocks.
47 | */
48 |
49 | /*! \brief Some text
50 | * \namespace FakeKnownProblemNamespace2
51 | */
52 |
53 | //! Code block with empty lines. Again, there are no characters to
54 | //! put the highlighting on, to make it appear like a box.
55 | //!
56 | //! \code
57 | //! if (true)
58 | //! {
59 | //!
60 | //! }
61 | //! \endcode
62 | void TestCodeBlockWithEmptyLine();
63 |
64 | //! Test code block where one "endcode" is missing.
65 | //!
66 | //! \code
67 | //! if (true)
68 | //! {
69 | //! ...
70 | //! }
71 | //!
72 | //! This should not be highlighted as code.
73 | //!
74 | //! \code
75 | //! if (true)
76 | //! {
77 | //! ...
78 | //! }
79 | //! \endcode
80 | void TestMissingEndCode();
81 |
82 | //! Test "verbatim".
83 | //!
84 | //! Currently, the `highlight-doxygen' package highlights verbatim
85 | //! blocks like code blocks. However, in reality EVERYTHING between
86 | //! "verbatim" and "endverbatim" is included, even comment start
87 | //! characters.
88 | //!
89 | //! \verbatim
90 | //! This block is verbatim (including the //! on this and the next line).
91 | //! \endverbatim
92 | void TestVerbatim();
93 |
94 | //! Test "verbatim" across Doxygen comments.
95 | //! \verbatim
96 | //! This is verbatim.
97 | void TestVerbatimAcrossComments_DoxygenThinksThisIsPartOfTheComment();
98 |
99 | //! This is also verbatim.
100 | //! \endverbatim
101 | //!
102 | //! Text after "verbatim".
103 |
104 | void TestVerbatimAcrossComments2();
105 | };
106 |
107 | // For code line comments, the "*/" should not be highlighted.
108 |
109 | int x;
110 |
111 | /*! \var int x; */
112 |
113 | // known-problems.h ends here
114 |
--------------------------------------------------------------------------------
/test/files/emphasis.h:
--------------------------------------------------------------------------------
1 | // code.h --- Example C++ code with emphasis comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2019 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // Example C++ code with emphasis comments.
27 |
28 | // Code:
29 |
30 | //! *This is emphasized* by Doxygen.
31 | //!
32 | //! *This*is*emphasized* by Doxygen.
33 | //!
34 | //! This is _also emphasized_ by Doxygen.
35 | //!
36 | //! This is _also_emphasized_ by Doxygen.
37 | //!
38 | //! **This is emphasized alot** by Doxygen.
39 | //!
40 | //! **This*is*emphasized*alot** by Doxygen.
41 | //!
42 | //! This is __also emphasized alot__ by Doxygen.
43 | //!
44 | //! This is __also_emphasized_alot__ by Doxygen.
45 | //!
46 | //! This is ~~strikedthrough~~ by Doxygen.
47 | //!
48 | //! This is ~~striked~~through~~ by Doxygen.
49 | //!
50 | //! ~~Double tilde~~
51 | //!
52 | //! This is `a piece is code`.
53 | //!
54 | //! Double backtick:s ``xxx`yyy``.
55 | //!
56 | //! Double backtick:s ``xxx`yyy`` and ``xxx`yyy``.
57 | //!
58 | //! Note: The following example is from the Doxygen manual. However,
59 | //! when passed through Doxygen, the quote to the left of "ls" is
60 | //! rendered using a code font, whereas the one to the right isn't. My
61 | //! conclusion is that the two *leftmost* backticks after "ls" is
62 | //! considerend the end of the code area, and the rightmost is emitted
63 | //! using a plain font.
64 | //!
65 | //! Double backtick:s ``var=`ls```.
66 | //!
67 | //! Likewise, seven out of the nine backticks are emitted using a
68 | //! non-code font.
69 | //!
70 | //! Double backtick:s ``xxx`yyy`````````.
71 | class TestEmphasize
72 | {
73 | };
74 |
75 |
76 | //! This*is*not*emphasized* by Doxygen.
77 | //!
78 | //! This is not_emphasized by Doxygen.
79 | //!
80 | //! This is `not code' as the plain quote undo the effect of the
81 | //! backtick.
82 | //!
83 | //! What about `this` 'this' `this' and `this`? (First and last is
84 | //! highlighted.)
85 | //!
86 | //! This is ~~not striked through~~ by Doxygen.
87 | class TestEmphasizeNegative
88 | {
89 | };
90 |
91 |
92 | //! Test `code
93 | //! spanning` multiple lines. (Handled by Doxygen.)
94 | //!
95 | //! Test ``code
96 | //! with double ` spanning`` multiple lines. (Handled by Doxygen.)
97 | //!
98 | //! Test *emphasis
99 | //! spanning* multiple lines. (Handled by Doxygen.)
100 | class TestEmphasizeMultiLine
101 | {
102 | };
103 |
104 |
105 | //! Test `code
106 | //!
107 | //! spanning` multiple paragraphs. (Not handled by Doxygen.)
108 | //!
109 | //! Test *emphasis
110 | //!
111 | //! spanning* multiple paragraphs. (Not handled by Doxygen.)
112 | class TestEmphasizeMultiParagraphs
113 | {
114 | };
115 |
--------------------------------------------------------------------------------
/test/files/verbatim.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:verbatim.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:Example C++ code with Doxygen "verbatim" blocks.
27 | »
28 | «m:// »«x:Code:
29 | »
30 | «m:// »«x:Note: It appears as though "verbatim" can't stretch across C++
31 | »«m:// »«x:comments. Also, it emits formatting like leading asterisks.
32 | »«m://»«x:
33 | »«m:// »«x:In most cases, a "\code" block or a MarkDown-style verbatim is
34 | »«m:// »«x:perferred.
35 | »
36 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This comment contains a "verbatim" block.
37 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
38 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:verbatim»
39 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:This is verbatim
40 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endverbatim»
41 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
42 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! More comments.
43 | »»
44 | «k:class» «t:TestVerbatimKeywordCpp»
45 | {
46 | };
47 |
48 |
49 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! This comment contains a "verbatim" block.
50 | *
51 | * The following will contain the " *":s in the output.
52 | *
53 | * \«:highlight-doxygen-command:verbatim»
54 | * «:highlight-doxygen-code-block:This is verbatim
55 | » * \«:highlight-doxygen-command:endverbatim»
56 | *
57 | * More comments.
58 | *
59 | * \«:highlight-doxygen-command:verbatim»
60 | «:highlight-doxygen-code-block:This is also verbatim
61 | »\«:highlight-doxygen-command:endverbatim»
62 | *
63 | */»»«:highlight-doxygen-comment:
64 | »
65 | «k:class» «t:TestVerbatimKeywordC»
66 | {
67 | };
68 |
69 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This comment contains a "verbatim" block.
70 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
71 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Note: When Doxygen renders the following paragraph, it is split
72 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! into three separate paragraphs, hence this isn't a good way to
73 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! write inline code snippets.
74 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
75 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! The following \«:highlight-doxygen-command:verbatim» «:highlight-doxygen-code-block:is verbatim »\«:highlight-doxygen-command:endverbatim» but this isn't.
76 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
77 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! More comments.
78 | »»
79 | «k:class» «t:TestVerbatimKeywordOneLine»
80 | {
81 | };
82 |
83 | «m:// »«x:verbatim.h ends here
84 | »
--------------------------------------------------------------------------------
/test/files/code.h:
--------------------------------------------------------------------------------
1 | // code.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // Example C++ code with Doxygen "code" blocks.
27 |
28 | // Code:
29 |
30 |
31 | //! This comment contains a "code" block.
32 | //!
33 | //! \code
34 | //! if (true)
35 | //! {
36 | //! ...
37 | //! }
38 | //! \endcode
39 | //!
40 | //! This text is after the code block.
41 |
42 | class TestCodeKeyword
43 | {
44 | };
45 |
46 | //! This comment contains a "code" block with a known extension.
47 | //!
48 | //! \code{.rb}
49 | //! def foo(&block b)
50 | //! {
51 | //! yield
52 | //! }
53 | //! \endcode
54 | //!
55 | //! This text is after the code block.
56 |
57 | class TestRubyCodeKeyword
58 | {
59 | };
60 |
61 | //! This comment contains a "code" block with an unknown extension.
62 | //!
63 | //! \code{.unknown}
64 | //! def foo(&block b)
65 | //! {
66 | //! yield
67 | //! }
68 | //! \endcode
69 | //!
70 | //! This text is after the code block.
71 |
72 | class TestUnknownCodeKeyword
73 | {
74 | };
75 |
76 | //! This comment contains a one-line "code" block.
77 | //!
78 | //! Note: When Doxygen renders the following paragraph, it is split
79 | //! into three separate paragraphs, hence this isn't a good way to
80 | //! write inline code snippets.
81 | //!
82 | //! Here comes some code \code while(true); \endcode but this isn't
83 | //! code.
84 | //!
85 | //! More comments.
86 |
87 | class TestCodeKeywordOneLine
88 | {
89 | };
90 |
91 | //! Testing dot. This relies on having the package
92 | //! `graphviz-dot-mode' installed.
93 | //!
94 | //! \dot
95 | //! digraph example {
96 | //! node [shape=record, fontname=Helvetica, fontsize=10];
97 | //! b [ label="class B" URL="\ref B"];
98 | //! c [ label="class C" URL="\ref C"];
99 | //! b -> c [ arrowhead="open", style="dashed" ];
100 | //! }
101 | //! \enddot
102 | //!
103 | //! Note: The following doesn't work properly.
104 | //!
105 | //! \dot "Caption" width=10cm
106 | //! digraph example {
107 | //! node [shape=record, fontname=Helvetica, fontsize=10];
108 | //! b [ label="class B" URL="\ref B"];
109 | //! c [ label="class C" URL="\ref C"];
110 | //! b -> c [ arrowhead="open", style="dashed" ];
111 | //! }
112 | //! \enddot
113 |
114 | class TestDotBlock
115 | {
116 | };
117 |
118 | //! Test code block indented with tabs
119 | //!
120 | //! Aligned with spaces.
121 | //!
122 | //! \code
123 | //! if (true) // Spaces
124 | //! { // Tab
125 | //! true; // Tab
126 | //! } // Spaces
127 | //! \endcode
128 | //!
129 | //! Not aligned.
130 | //!
131 | //! \code
132 | //! if (true) // Spaces
133 | //! { // Spaces
134 | //! true; // Tab
135 | //! } // Spaces
136 | //! \endcode
137 | //!
138 | //! Multiple tabs.
139 | //!
140 | //! \code
141 | //! if (true) // Spaces
142 | //! { // Tab
143 | //! true; // Tab
144 | //! } // Spaces
145 | //! \endcode
146 | //!
147 | //! Not aligned.
148 | //!
149 | //! \code
150 | //! if (true) // Spaces
151 | //! { // Spaces
152 | //! true; // Tab
153 | //! } // Spaces
154 | //! \endcode
155 | //!
156 |
157 | // code.h ends here
158 |
--------------------------------------------------------------------------------
/test/files/markdown.h:
--------------------------------------------------------------------------------
1 | // markdown.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // Example C++ code with Doxygen markdown-style blocks.
27 |
28 | // Code:
29 |
30 | //! This comment contains an implicit verbatim block.
31 | //!
32 | //! This is verbatim
33 | //! And this too.
34 | //!
35 | //! Just check so that verbatim blocks aren't treated as code:
36 | //!
37 | //! if (true)
38 | //! {
39 | //! ...
40 | //! }
41 | //!
42 | //! End of comment.
43 |
44 | class TestVerbatimImplicit
45 | {
46 | public:
47 | /*!
48 | *
49 | * The following is not seen as a verbatim block by Doxygen
50 | *
51 | * Zero
52 | * One
53 | * Two
54 | * Three
55 | * Four
56 | * Five
57 | * Six
58 | * Seven
59 | * Eight
60 | *
61 | * Part of the following is seen as verbatim block by Doxygen.
62 | *
63 | * Eight
64 | * Seven
65 | * Six
66 | * Five
67 | * Four <---- Last line of the block
68 | * Three
69 | * Two
70 | * One
71 | * Zero
72 | *
73 | * This is more plain text.
74 | */
75 | void TestVariableIndentation();
76 |
77 | // The following two test shows that the block must be indented four
78 | // spaces more than the surrounding text, even if the surrounding
79 | // text starts one column to the right due to the "!" sign.
80 |
81 | /*! Test initial block.
82 | *
83 | * Four spaces. Not seen as block by Doxygen.
84 | */
85 | void TestInitialBlock4();
86 |
87 | /*! Test initial block.
88 | *
89 | * Five spaces. Seen as block by Doxygen.
90 | */
91 | void TestInitialBlock5();
92 |
93 | /*! Test block at the end.
94 | *
95 | * This is plain text.
96 | *
97 | * This is a block
98 | */
99 | void TestBlockAtTheEnd();
100 |
101 | /*! Test if block can start without an empty line. (No, they can't.)
102 | *
103 | * Text
104 | * Maybe block
105 | *
106 | * Text2
107 | * Maybe block
108 | * Text3
109 | */
110 | void TestTightBlock();
111 |
112 | /*! Test if blocks indented a bit at a time is seen as a block.
113 | *
114 | * Text1
115 | *
116 | * Text2
117 | *
118 | * Text3
119 | *
120 | * Text4 <- Indented with 4 spaces, seen as block.
121 | *
122 | * Text5
123 | *
124 | * Text6
125 | *
126 | * Text1
127 | *
128 | * Text2
129 | *
130 | * Text3
131 | *
132 | * Text4 <- Indented with 4 spaces, seen as block.
133 | * Text5 <- Not part of block.
134 | * Text6
135 | */
136 | void TestStaggering();
137 |
138 | /*!
139 | * Test if a block can start with a more indented line.
140 | *
141 | * Text8
142 | * Text7
143 | *
144 | * Text after.
145 | */
146 | void TestMoreIndented();
147 |
148 | //!
149 | void TestEmptySlashSlashComment();
150 |
151 | //! Test code block at end of C++ comment.
152 | //!
153 | //! if (test)
154 | //! {
155 | //! ..
156 | //! }
157 | void TestEndOfSlashSlashComment();
158 |
159 | //! Test MarkDown code blocks after non-straight left margin.
160 | //!
161 | //! Alpha
162 | //! Beta
163 | //! Gamma
164 | //!
165 | //! Is this a code block? (NO, according to Doxygen)
166 | //!
167 | //! Alpha
168 | //! Beta
169 | //! Gamma
170 | //!
171 | //! Is this a code block? (YES, according to Doxygen)
172 | //!
173 | //! Alpha
174 | //! Beta
175 | //! Gamma
176 | //!
177 | //! Is this a code block? (YES, according to Doxygen)
178 | void TestNonStraightMargin();
179 |
180 | //! Test code block with empty lines
181 | //!
182 | //! Empty line (no spaces):
183 | //!
184 | //! if (test)
185 | //! {
186 | //!
187 | //! }
188 | void TestEmptyLinesInCodeBlock();
189 |
190 | //! Test explicit code blocks.
191 | //!
192 | //! Explicit code block:
193 | //!
194 | //! \code
195 | //! if (test)
196 | //! {
197 | //!
198 | //! }
199 | //! \endcode
200 | //!
201 | //! Explicit code block after markdown block:
202 | //!
203 | //! Is this a code block? (YES, according to Doxygen)
204 | //!
205 | //! \code
206 | //! if (test)
207 | //! {
208 | //!
209 | //! }
210 | //! \endcode
211 | //!
212 | //! Explicit code block before markdown block, same indentation:
213 | //!
214 | //! \code
215 | //! if (test)
216 | //! {
217 | //!
218 | //! }
219 | //! \endcode
220 | //!
221 | //! Is this a code block? (NO, according to Doxygen)
222 | //!
223 | //! Explicit code block before markdown block, more indentation:
224 | //!
225 | //! \code
226 | //! if (test)
227 | //! {
228 | //!
229 | //! }
230 | //! \endcode
231 | //!
232 | //! Is this a code block? (YES, according to Doxygen)
233 | //!
234 | //! Explicit code block before markdown block, commands indented:
235 | //!
236 | //! \code
237 | //! if (test)
238 | //! {
239 | //!
240 | //! }
241 | //! \endcode
242 | //!
243 | //! Is this a code block? (NO, according to Doxygen)
244 | void TestMixExplicitAndImplicit();
245 | };
246 |
247 | // markdown.h ends here
248 |
--------------------------------------------------------------------------------
/test/files/sections.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:sections.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:This file contains Doxygen commands for writing sections and pages.
27 | »
28 | «m:// »«x:Code:
29 | »
30 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:mainpage» «:highlight-doxygen-heading-1:This is the title of the documentation»
31 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
32 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the body text of the main page.
33 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
34 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:section» «:highlight-doxygen-label:sec1»«:highlight-doxygen-heading-2: This is the first section»
35 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
36 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the body text of the first section.
37 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
38 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:par» «:highlight-doxygen-heading-4:This is a paragraph title»
39 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Paragraph body.
40 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
41 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:vhdlflow» «:highlight-doxygen-heading-4:This is VHDL diagram title»
42 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Paragraph body. (This only work in VHDL...)
43 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
44 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:section» «:highlight-doxygen-label:sec2»«:highlight-doxygen-heading-2: This is the second section»
45 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
46 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the body text of the second section.
47 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
48 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:subsection» «:highlight-doxygen-label:sub21»«:highlight-doxygen-heading-3: This is a subsection»
49 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
50 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the body text of the subsection.
51 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
52 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! In \«:highlight-doxygen-command:ref» «:highlight-doxygen-link:sec1» and \«:highlight-doxygen-command:ref» «:highlight-doxygen-link:par211» you can read more.
53 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
54 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:subsubsection» «:highlight-doxygen-label:sub211»«:highlight-doxygen-heading-4: This is a subsubsection»
55 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
56 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the body text of the subsubsection.
57 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
58 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:paragraph» «:highlight-doxygen-label:par211»«:highlight-doxygen-heading-5: This is a paragraph in the subsubsection»
59 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
60 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the body of the paragraph.
61 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
62 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! And more text (wonder where this will go).
63 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
64 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:page» «:highlight-doxygen-label:page1»«:highlight-doxygen-heading-2: This is a page»
65 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
66 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Without quotes.
67 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
68 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:page» «:highlight-doxygen-label:page2»«:highlight-doxygen-heading-2: "This is another page"»
69 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
70 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! With quotes. (Incorrectly formed for Doxygen)
71 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
72 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:subpage» «:highlight-doxygen-label:subpage1»«:highlight-doxygen-heading-3: This is a subpage»
73 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
74 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Without quotes. (Incorrectly formed for Doxygen)
75 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
76 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:subpage» «:highlight-doxygen-label:subpage2»«:highlight-doxygen-heading-3: "This is another page"»
77 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
78 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! With quotes.
79 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
80 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:subpage» «:highlight-doxygen-label:subpage3»
81 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
82 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Without title.
83 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
84 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! And even more text (wonder where this will go).
85 | »»
86 | «m:// »«x:sections.h ends here
87 | »
--------------------------------------------------------------------------------
/test/files/known-problems.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:known-problems.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:Example C++ code with Doxygen comments demonstrates a number of
27 | »«m:// »«x:known problems with the `highlight-doxygen' package.
28 | »
29 | «m:// »«x:Code:
30 | »
31 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Doxygen comments with known problems.
32 | »»«k:class» «t:TestKnownProblemsClass»
33 | {
34 | «k:public»:
35 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! This is a C-style block.
36 | » «:highlight-doxygen-comment: The package can't highlight the following empty line as the rest
37 | » «:highlight-doxygen-comment: of the block, because there are no characters on it to highlight.
38 |
39 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
40 | » «t:void» «f:TestCStyleBlocksWithEmptyLines»();
41 |
42 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:brief» Some text
43 | » «:highlight-doxygen-comment: * \«:highlight-doxygen-command:namespace» «t:«:highlight-doxygen-namespace:FakeKnownProblemNamespace»»
44 | » «:highlight-doxygen-comment: *
45 | » «:highlight-doxygen-comment: * This and the next comment should be highlighted as separate
46 | » «:highlight-doxygen-comment: * comment blocks.
47 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
48 |
49 | » «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:brief» Some text
50 | » «:highlight-doxygen-comment: * \«:highlight-doxygen-command:namespace» «t:«:highlight-doxygen-namespace:FakeKnownProblemNamespace2»»
51 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
52 |
53 | » «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Code block with empty lines. Again, there are no characters to
54 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! put the highlighting on, to make it appear like a box.
55 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
56 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
57 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» («c:true»)
58 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
59 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
60 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
61 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
62 | »» «t:void» «f:TestCodeBlockWithEmptyLine»();
63 |
64 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test code block where one "endcode" is missing.
65 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
66 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
67 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «k:if» («c:true»)
68 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: {
69 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: ...
70 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: }
71 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
72 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«t:This» «v:should» «k:not» be highlighted as code.
73 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
74 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:\code
75 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «k:if» («c:true»)
76 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: {
77 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: ...
78 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: }
79 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
80 | »» «t:void» «f:TestMissingEndCode»();
81 |
82 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test "verbatim".
83 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
84 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Currently, the `highlight-doxygen' package highlights verbatim
85 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! blocks like code blocks. However, in reality EVERYTHING between
86 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! "verbatim" and "endverbatim" is included, even comment start
87 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! characters.
88 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
89 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:verbatim»
90 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:This block is verbatim (including the //! on this and the next line).
91 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endverbatim»
92 | »» «t:void» «f:TestVerbatim»();
93 |
94 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test "verbatim" across Doxygen comments.
95 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:verbatim»
96 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is verbatim.
97 | »» «t:void» «f:TestVerbatimAcrossComments_DoxygenThinksThisIsPartOfTheComment»();
98 |
99 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is also verbatim.
100 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endverbatim»
101 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
102 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Text after "verbatim".
103 | »»
104 | «t:void» «f:TestVerbatimAcrossComments2»();
105 | };
106 |
107 | «m:// »«x:For code line comments, the "*/" should not be highlighted.
108 | »
109 | «t:int» «v:x»;
110 |
111 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:var» «:highlight-doxygen-code-block:«t:int» «v:x»; */»»»«:highlight-doxygen-comment:
112 | »
113 | «m:// »«x:known-problems.h ends here
114 | »
--------------------------------------------------------------------------------
/test/highlight-doxygen-test-basic.el:
--------------------------------------------------------------------------------
1 | ;;; highlight-doxygen-test-basic.el --- Test primitive functions.
2 |
3 | ;; Copyright (C) 2018 Anders Lindgren
4 |
5 | ;; Author: Anders Lindgren
6 |
7 | ;; This file is part of the `highlight-doxygen' package.
8 |
9 | ;; This program is free software; you can redistribute it and/or modify
10 | ;; it under the terms of the GNU General Public License as published by
11 | ;; the Free Software Foundation, either version 3 of the License, or
12 | ;; (at your option) any later version.
13 |
14 | ;; This program is distributed in the hope that it will be useful,
15 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 | ;; GNU General Public License for more details.
18 |
19 | ;; You should have received a copy of the GNU General Public License
20 | ;; along with this program. If not, see .
21 |
22 | ;;; Commentary:
23 |
24 | ;; Test primitive functions in `highlight-doxygen'.
25 |
26 | ;;; Code:
27 |
28 |
29 | ;; ------------------------------------------------------------
30 | ;; Test `highlight-doxygen-forward-to-indentation'
31 | ;;
32 |
33 | (defun highlight-doxygen-test-basic--forward-to-indentation (str)
34 | "Call `highlight-doxygen-forward-to-indentation' with buffer containing STR.
35 |
36 | The point is placed on the location of the `|' character and the
37 | character is delected before the function is called.
38 |
39 | If `highlight-doxygen-forward-to-indentation' returns non-nil the
40 | current column is returned. Otherwise, nil is returned."
41 | (with-temp-buffer
42 | (c++-mode)
43 | (save-excursion
44 | (insert str))
45 | (when (search-forward "|" nil t)
46 | (delete-region (match-beginning 0) (match-end 0)))
47 | (and (highlight-doxygen-forward-to-indentation)
48 | (current-column))))
49 |
50 |
51 | (ert-deftest highlight-doxygen-test-basic--forward-to-indentation ()
52 | ;; Without indentation.
53 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
54 | "|//!")
55 | nil))
56 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
57 | "|//! ")
58 | nil))
59 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
60 | "|//! ")
61 | nil))
62 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
63 | "|//!\t")
64 | nil))
65 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
66 | "|//!\t\t")
67 | nil))
68 | ;; With indentation.
69 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
70 | "|//!xxx")
71 | 3))
72 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
73 | "|//! xxx")
74 | 4))
75 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
76 | "|//! xxx")
77 | 5))
78 | ;; C-style comments.
79 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
80 | "\
81 | |/*!
82 | */")
83 | nil))
84 | ;; Note: The current implementation incorrectly see the "/" as part
85 | ;; of the text block. However, in practice it doesn't matter. (It
86 | ;; would be better if it would return nil in this case.)
87 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
88 | "\
89 | /*!
90 | | */")
91 | 3))
92 | (should (equal (highlight-doxygen-test-basic--forward-to-indentation
93 | "\
94 | /*!
95 | | * /
96 | */")
97 | 3))
98 | nil)
99 |
100 |
101 | ;; ------------------------------------------------------------
102 | ;; Test `highlight-doxygen-next-comment'
103 | ;;
104 |
105 | (defun highlight-doxygen-test-basic--next-comment (str &optional explain)
106 | ""
107 | (with-temp-buffer
108 | (c++-mode)
109 | (save-excursion
110 | (insert str))
111 | ;; Prep the list with `positions' to make the output of the
112 | ;; explainer nicer when one of the list otherwise would have been
113 | ;; empty.
114 | (let ((reference-positions '(positions)))
115 | (while (search-forward "|" nil t)
116 | (delete-region (match-beginning 0) (match-end 0))
117 | (push (point) reference-positions))
118 | (goto-char (point-min))
119 | (let ((real-positions '(positions)))
120 | (while (highlight-doxygen-next-comment (point-max))
121 | (push (point) real-positions)
122 | ;; Needed, since `h-d-next-char' leaves point at the
123 | ;; beginning of a comment, and when reapplied, the point
124 | ;; doesn't move. (Maybe this should be changed?)
125 | (forward-char))
126 | (funcall
127 | (if explain
128 | (get 'equal 'ert-explainer)
129 | #'equal)
130 | (reverse reference-positions)
131 | (reverse real-positions))))))
132 |
133 | (put 'highlight-doxygen-test-basic--next-comment
134 | 'ert-explainer
135 | (lambda (str)
136 | (highlight-doxygen-test-basic--next-comment str t)))
137 |
138 |
139 | (ert-deftest highlight-doxygen-test-basic--next-comment ()
140 | ;; Plain comments.
141 | (should (highlight-doxygen-test-basic--next-comment ""))
142 | (should (highlight-doxygen-test-basic--next-comment "|//!"))
143 | (should (highlight-doxygen-test-basic--next-comment "\
144 | |//! bla
145 | |//! bla"))
146 | ;; Comments in comments.
147 | (should (highlight-doxygen-test-basic--next-comment "\
148 | |//! bla //! bla
149 | |//! bla //! bla"))
150 | (should (highlight-doxygen-test-basic--next-comment "\
151 | // bla //! bla
152 | // bla //! bla"))
153 | ;; Comments in strings
154 | (should (highlight-doxygen-test-basic--next-comment "\
155 | foo(\"//! bla\""))
156 | (should (highlight-doxygen-test-basic--next-comment "\
157 | foo(\"bla //! bla\""))
158 | nil)
159 |
160 |
161 | ;; ------------------------------------------------------------
162 | ;; Test `highlight-doxygen-end-of-paragraph-position'
163 | ;;
164 |
165 | (defun highlight-doxygen-test-eopp (position limit &optional explain)
166 | "Check that the end of paragraph is POSITION.
167 |
168 | Move point to the next beginning of next line."
169 | (prog1
170 | (funcall
171 | (if explain
172 | (get 'equal 'ert-explainer)
173 | #'equal)
174 | (highlight-doxygen-end-of-paragraph-position limit)
175 | position)
176 | (unless explain
177 | (forward-line))))
178 |
179 | (put 'highlight-doxygen-test-eopp
180 | 'ert-explainer
181 | (lambda (position limit)
182 | (highlight-doxygen-test-eopp position limit t)))
183 |
184 |
185 | (ert-deftest highlight-doxygen-test-eopp ()
186 | "Test `highlight-doxygen-end-of-paragraph-position'."
187 | (with-temp-buffer
188 | (c++-mode)
189 | (let (p1 p2 p3)
190 | (save-excursion
191 | (insert "//! XXXXX\n")
192 | (setq p1 (- (point) 1))
193 | (insert "//!\n")
194 | (insert "//! XXXXX\n")
195 | (insert "//! XXXXX\n")
196 | (setq p2 (- (point) 1))
197 | (insert "//! \n")
198 | (insert "//! XXXXX\n")
199 | (setq p3 (- (point) 1))
200 | (insert "//!\n")
201 | (insert "//!\n"))
202 | (should (highlight-doxygen-test-eopp p1 (point-max)))
203 | (should (highlight-doxygen-test-eopp p2 (point-max)))
204 | (should (highlight-doxygen-test-eopp p2 (point-max)))
205 | (should (highlight-doxygen-test-eopp p2 (point-max)))
206 | (should (highlight-doxygen-test-eopp p3 (point-max)))
207 | (should (highlight-doxygen-test-eopp p3 (point-max)))
208 | (should (highlight-doxygen-test-eopp nil (point-max)))
209 | (should (highlight-doxygen-test-eopp nil (point-max))))))
210 |
211 |
212 | ;; ------------------------------------------------------------
213 | ;; The end
214 | ;;
215 |
216 | (provide 'highlight-doxygen-test-basic)
217 |
218 | ;;; highlight-doxygen-test-basic.el ends here
219 |
--------------------------------------------------------------------------------
/test/files/code.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:code.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:Example C++ code with Doxygen "code" blocks.
27 | »
28 | «m:// »«x:Code:
29 | »
30 |
31 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This comment contains a "code" block.
32 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
33 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
34 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» («c:true»)
35 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
36 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: ...
37 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
38 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
39 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
40 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This text is after the code block.
41 | »»
42 | «k:class» «t:TestCodeKeyword»
43 | {
44 | };
45 |
46 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This comment contains a "code" block with a known extension.
47 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
48 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»{.rb}
49 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:def» «f:foo»(&block b)
50 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
51 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «k:yield»
52 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
53 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
54 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
55 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This text is after the code block.
56 | »»
57 | «k:class» «t:TestRubyCodeKeyword»
58 | {
59 | };
60 |
61 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This comment contains a "code" block with an unknown extension.
62 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
63 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»{.unknown}
64 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:def foo(&block b)
65 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
66 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: yield
67 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
68 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
69 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
70 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This text is after the code block.
71 | »»
72 | «k:class» «t:TestUnknownCodeKeyword»
73 | {
74 | };
75 |
76 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This comment contains a one-line "code" block.
77 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
78 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Note: When Doxygen renders the following paragraph, it is split
79 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! into three separate paragraphs, hence this isn't a good way to
80 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! write inline code snippets.
81 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
82 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Here comes some code \«:highlight-doxygen-command:code» «:highlight-doxygen-code-block:«k:while»(«c:true»); »\«:highlight-doxygen-command:endcode» but this isn't
83 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! code.
84 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
85 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! More comments.
86 | »»
87 | «k:class» «t:TestCodeKeywordOneLine»
88 | {
89 | };
90 |
91 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Testing dot. This relies on having the package
92 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! `graphviz-dot-mode' installed.
93 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
94 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dot»
95 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:digraph example {
96 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:node [shape=record, fontname=Helvetica, fontsize=10];
97 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: b [ label="class B" URL="\ref B"];
98 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: c [ label="class C" URL="\ref C"];
99 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: b -> c [ arrowhead="open", style="dashed" ];
100 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
101 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:enddot»
102 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
103 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Note: The following doesn't work properly.
104 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
105 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:\«:highlight-doxygen-command:dot» "Caption" width=10cm
106 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:digraph example {
107 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:node [shape=record, fontname=Helvetica, fontsize=10];
108 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: b [ label="class B" URL="\ref B"];
109 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: c [ label="class C" URL="\ref C"];
110 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: b -> c [ arrowhead="open", style="dashed" ];
111 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
112 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:enddot»
113 | »»
114 | «k:class» «t:TestDotBlock»
115 | {
116 | };
117 |
118 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test code block indented with tabs
119 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
120 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Aligned with spaces.
121 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
122 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
123 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» («c:true») «:highlight-doxygen-code-block:// Spaces»
124 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{ «:highlight-doxygen-code-block:// Tab»
125 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «c:true»; «:highlight-doxygen-code-block:// Tab»
126 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:} «:highlight-doxygen-code-block:// Spaces»
127 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
128 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
129 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Not aligned.
130 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
131 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
132 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» («c:true») «:highlight-doxygen-code-block:// Spaces»
133 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{ «:highlight-doxygen-code-block:// Spaces»
134 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!«:highlight-doxygen-code-block: «c:true»; «:highlight-doxygen-code-block:// Tab»
135 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:} «:highlight-doxygen-code-block:// Spaces»
136 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
137 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
138 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Multiple tabs.
139 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
140 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
141 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» («c:true») «:highlight-doxygen-code-block:// Spaces»
142 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{ «:highlight-doxygen-code-block:// Tab»
143 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «c:true»; «:highlight-doxygen-code-block:// Tab»
144 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:} «:highlight-doxygen-code-block:// Spaces»
145 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
146 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
147 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Not aligned.
148 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
149 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
150 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» («c:true») «:highlight-doxygen-code-block:// Spaces»
151 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{ «:highlight-doxygen-code-block:// Spaces»
152 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: «c:true»; «:highlight-doxygen-code-block:// Tab»
153 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:} «:highlight-doxygen-code-block:// Spaces»
154 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
155 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
156 | »»
157 | «m:// »«x:code.h ends here
158 | »
--------------------------------------------------------------------------------
/test/files/normal.h:
--------------------------------------------------------------------------------
1 | // normal.h --- Example C++ code with Doxygen comments.
2 |
3 | // Commentary:
4 |
5 | // Copyright (C) 2018 Anders Lindgren
6 |
7 | // Author: Anders Lindgren
8 |
9 | // This file is part of the `highlight-doxygen' package.
10 |
11 | // This program is free software; you can redistribute it and/or modify
12 | // it under the terms of the GNU General Public License as published by
13 | // the Free Software Foundation, either version 3 of the License, or
14 | // (at your option) any later version.
15 |
16 | // This program is distributed in the hope that it will be useful,
17 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | // GNU General Public License for more details.
20 |
21 | // You should have received a copy of the GNU General Public License
22 | // along with this program. If not, see .
23 |
24 | // Commentary:
25 |
26 | // Example C++ code with Doxygen comments demonstrates a number of
27 | // known problems with the `highlight-doxygen' package.
28 |
29 | // Code:
30 |
31 | // This file contains most, if not all, doxygen commands.
32 | //
33 | // The main purpouse of this file is for regression testing of the
34 | // Emacs package "highlight-doxygen".
35 | //
36 | // Doxygen comments with code examples are in separate files.
37 |
38 | // Conventions:
39 | //
40 | // Constructs defined in this file are named TestXxx.
41 | //
42 | // Constructs defined using doxygen commands like "\class" are named
43 | // FakeXxx or fakexxxx.
44 |
45 |
46 | // ------------------------------------------------------------
47 | // Commands that define construct somewhere else
48 | //
49 |
50 | // TODO: The [header-file] [header-name] syntax in all of the following:
51 |
52 | //! \class fakeclass
53 | //!
54 | //! This is a fake class.
55 |
56 | //! \class FakeClass
57 | //!
58 | //! This is a fake class.
59 |
60 | //! \enum fakeenum
61 | //!
62 | //! This is a fake enum.
63 |
64 | //! \enum FakeEnum
65 | //!
66 | //! This is a fake enum.
67 |
68 | //! \interface fakeinterface
69 | //!
70 | //! This is a fake interface.
71 |
72 | //! \interface FakeInterface
73 | //!
74 | //! This is a fake interface.
75 |
76 | //! \namespace fakenamespace
77 | //!
78 | //! This is a fake namespace.
79 |
80 | //! \namespace FakeNamespace
81 | //!
82 | //! This is a fake namespace.
83 |
84 | //! \namespace fakeparent::fakenamespace
85 | //!
86 | //! This is a fake namespace.
87 |
88 | //! \namespace FakeParent::FakeNamespace
89 | //!
90 | //! This is a fake namespace.
91 |
92 | //! \struct fakestruct
93 | //!
94 | //! This is a fake struct.
95 |
96 | //! \struct FakeStruct
97 | //!
98 | //! This is a fake struct.
99 |
100 | //! \union fakeunion
101 | //!
102 | //! This is a fake union.
103 |
104 | //! \union FakeUnion
105 | //!
106 | //! This is a fake union.
107 |
108 | // Note: Objective-C.
109 |
110 | //! \category fakecategory
111 | //!
112 | //! This is a fake category.
113 |
114 | //! \category FakeCategory
115 | //!
116 | //! This is a fake category.
117 |
118 | //! \protocol fakeprotocol
119 | //!
120 | //! This is a fake protocol.
121 |
122 | //! \protocol FakeProtocol
123 | //!
124 | //! This is a fake protocol.
125 |
126 |
127 |
128 | // --------------------
129 | // Class
130 | //
131 |
132 | //! Class for testing "related" etc.
133 | class TypeClass
134 | {
135 | };
136 |
137 | //! A related function. \relates TypeClass.
138 | void TestRelates(void);
139 |
140 | //! This is a namespace.
141 | namespace TestNamespace
142 | {
143 | }
144 |
145 | //! This is a union.
146 | union TestUnion
147 | {
148 | };
149 |
150 | //! This is an enum.
151 | enum TypeEnum
152 | {
153 | };
154 |
155 |
156 | //! Template class.
157 | //!
158 | //! \tparam arraysize size of array.
159 | template
160 | class TestTemplateClass
161 | {
162 | int arr[arraysize];
163 | };
164 |
165 |
166 | //! Function that throws.
167 | //!
168 | //! \throw TestException
169 | //! \throw Simple
170 | //! \throw lowercase
171 | //! \throw Qualified::Tip
172 | void TestThrows() throw TestException;
173 |
174 | //! Another function that throws.
175 | //!
176 | //! \throw std::out_of_range.
177 | void TestThrows2() throw std::out_of_range;
178 |
179 | // --------------------
180 | // section-label
181 | //
182 |
183 | //! \if alabel
184 | //! This is the "this" part.
185 | //! \elseif alabel
186 | //! This is the "else" part.
187 | //! \endif
188 |
189 | void TestSectionLabel();
190 |
191 | //! \ifnot alabel
192 | //! This is the "this" part.
193 | //! \elseif alabel
194 | //! This is the "else" part.
195 | //! \endif
196 |
197 | void TestSectionLabel2();
198 |
199 |
200 | // --------------------
201 | // Groups
202 | //
203 |
204 | //! \defgroup group1 This is a group title.
205 | //! This is a group body.
206 |
207 | //! \addtogroup group1
208 | //! More group body.
209 |
210 | //! \weakgroup my_weak_group
211 | //! This is a weak group.
212 |
213 | //! \ingroup group1
214 | //! This is in group1.
215 |
216 | void TestIngroup(void);
217 |
218 | // TODO: Add support for specifying multiple groups.
219 |
220 | //! \ingroup group1 my_weak_group
221 | //! This is in group1 and my_weak_group.
222 |
223 | void TestIngroup2(void);
224 |
225 | //! \dir This/is/a/dir
226 |
227 | void TestDir(void);
228 |
229 | // TODO: If Doxygen can handle this, ensure we can too.
230 |
231 | //! \dir "This is a path with spaces"
232 |
233 | void TestDir2(void);
234 |
235 | // TODO: Check how Doxygen handle this.
236 |
237 | //! \dir a_dir This is not a dir.
238 |
239 | void TestDir3(void);
240 |
241 | // --------------------
242 | // With filename arguments.
243 |
244 | // Syntax:
245 | //
246 | // \class name [] []
247 |
248 |
249 | // Note: The "." isn't written in verbatim, as that produces a link.
250 |
251 | // Conclusion: can be foo.h or "foo.h".
252 |
253 | //! \class FakeClassNameP other.h
254 | //! Class with other dot h
255 |
256 | //! \class FakeClassNameQ "other.h"
257 | //! Class with "other dot h"
258 |
259 | //! \class FakeClassNamePP other.h sub/other.h
260 | //! Class with other dot h sub/other dot h
261 |
262 | //! \class FakeClassNamePQ other.h "sub/other.h"
263 | //! Class with other dot h "sub/other dot h".
264 |
265 | //! \class FakeClassNamePS other.h
266 | //! Class with other dot h \.
267 |
268 | /**
269 | * \a arg
270 | */
271 |
272 | // Note: The following doesn't seem to work in doxygen.
273 | //
274 | // The documentation specifies:
275 | //
276 | // \class name [] []
277 | //
278 | // I guess that the documentation should read:
279 | //
280 | // \class name [ []]
281 |
282 | #if 0
283 | //! \class FakeClassNameSubP sub/other.h
284 | //! Class with sub/other dot h.
285 |
286 | //! \class FakeClassNameSubQ "sub/other.h"
287 | //! Class with "sub/other dot h".
288 |
289 | // This fails badly, it generates "#include <<>".
290 |
291 | //! \class FakeClassNameS
292 | //! Class with \
293 |
294 | //! \class FakeClassNameSubS
295 | //! Class with \.
296 | #endif
297 |
298 |
299 | // TODO: This is another animal than the above.
300 |
301 | //! \exception fakeexception
302 | //!
303 | //! This is a fake exception.
304 |
305 | //! \exception FakeException
306 | //!
307 | //! This is a fake exception.
308 |
309 | //! This is a \throw throw but this isn't.
310 | //!
311 |
312 |
313 | // ------------------------------------------------------------
314 | // Commands that define constructs in the file
315 | //
316 |
317 | // Place this is a comment OF something.
318 |
319 | //! Link to the other.h header file.
320 |
321 |
322 |
323 | //! Commands that take a variable as argument.
324 | //!
325 | //! TODO: param
326 | //!
327 | //! This is a \a parameter but this isn't.
328 | //!
329 | //! TODO: Is this really a variable?
330 | //!
331 | //! This is \relates relates but this doesn't.
332 | //!
333 | //! This is \relatesalso relatesalso but this doesn't.
334 | //!
335 | //! This is a \var variable but this isn't.
336 | //!
337 | //! This is a \def variable but this isn't.
338 | //!
339 | //! This \implements FakeClass::FakeFunction.
340 | //!
341 | //! This \implements fakeclass::fakefunction.
342 |
343 | class TestVarArgs
344 | {
345 | };
346 |
347 |
348 |
349 | //! Test if the argument can be placed on another line.
350 | //!
351 | //! Highlighting for this is currently not supported.
352 | //!
353 | class TestLineBreaks
354 | {
355 | public:
356 | //! Test if \a
357 | //! my_argument can be on the next line.
358 | //!
359 | //! Check if there can be an empty line between the command and the
360 | //! agument, like \a
361 | //!
362 | //! arg2 here.
363 | //!
364 | //! Doxygen handles line breaks, but not empty lines.
365 | void TestLineBreaks(int my_argument, int arg2)
366 | {
367 | }
368 | };
369 |
370 |
371 | //! Commands that take a function name as arguments:
372 | //!
373 | //! This is a \retval function but this isn't.
374 |
375 | class TestRetval
376 | {
377 | };
378 |
379 |
380 | //! Commands that take a "word" as argument:
381 | //!
382 | //! This is a \a parameter but this isn't.
383 | //!
384 | //! This is a \p parameter but this isn't.
385 | //!
386 | //! This is an \anchor anchor but this isn't.
387 | //!
388 | //! This is \b bold but this isn't.
389 | //!
390 | //! This is \c code but this isn't.
391 | //!
392 | //! This is \e emphasized but this isn't.
393 | //!
394 | //! This is \em emphasized but this isn't.
395 | //!
396 | //! \retval ZERO if \p parameter is zero
397 | //! \retval NONZERO if \p parameter is non-zero
398 |
399 | int TestWordFunction(int parameter)
400 | {
401 | if (parameter > 0)
402 | {
403 | return NONZERO;
404 | }
405 | else
406 | {
407 | return ZERO;
408 | }
409 | }
410 |
411 | //! Parameter commands
412 | //!
413 | //! \param plain a plain parameter
414 | //! \param [in] x an "in" parameter
415 | //! \param [out] y an "in" parameter
416 | //! \param [in,out] z an "in" parameter
417 | //!
418 | //! Without whitespace:
419 | //!
420 | //! \param[in]x an "in" parameter
421 | //! \param[out]y an "in" parameter
422 | //! \param[in,out]z an "in" parameter
423 | //!
424 | //! Partially written:
425 | //!
426 | //! \param[in]
427 |
428 | void test(int plain, int x, int y, int z);
429 |
430 |
431 | //! \sa TestOptional
432 | //!
433 | //! \sa Paragraph with TestOptional reference.
434 | //!
435 | //! \sa http://www.some-company.com/a%20page.html
436 | //!
437 | //! \sa This is a paragraph with links like this one
438 | //! http://www.some-company.com/a%20page.html and
439 | //! function_like_this_one().
440 |
441 | class TestSeeAlso
442 | {
443 | };
444 |
445 | // TODO: link copydoc xrefitem if ifnot elseif
446 |
447 | //! Commands that take an optional argument:
448 | //!
449 | //! TODO: How?
450 | //!
451 | //! \cond
452 | //!
453 | //! \cond argument
454 | //!
455 | //! \cond argument1 argument2
456 | //!
457 | //! \endcond
458 | //!
459 | //! \endcond
460 | //!
461 | //! \endcond
462 | //!
463 | //! \dir
464 | //!
465 | //! \dir argument
466 | //!
467 | //! \dir argument1 argument2
468 | //!
469 | //! \~
470 | //!
471 | //! \~argument
472 | //!
473 | //! \~argument1 argument2
474 |
475 | class TestOptional
476 | {
477 | };
478 |
479 |
480 | //! \ref a_reference but this isn't.
481 |
482 | class TestReference
483 | {
484 | };
485 |
486 |
487 | //! Testing filenames:
488 | //!
489 | //! This is an \example example but this isn't.
490 | //!
491 | //! This is an \example example.cpp but this isn't.
492 | //!
493 | //! This is an \example "example.cpp" but this isn't.
494 | //!
495 | //! This is an \example "a/path/to/an/example.cpp" but this isn't.
496 | //!
497 | //! This is an \example "a\path\to\an\example.cpp" but this isn't.
498 | //!
499 | //! This is an \example "a path with spaces/example.cpp" but this isn't.
500 | //!
501 | //! This is an \example "a path with spaces\example.cpp" but this isn't.
502 |
503 | class TestFilename1
504 | {
505 | };
506 |
507 | //! Commands that take a file name as arguments:
508 | //!
509 | //! This is an \example example.h but this isn't.
510 | //!
511 | //! This is a \dont dont.h but this isn't.
512 | //!
513 | //! This is a \dontinclude dontinclude.h but this isn't.
514 | //!
515 | //! This is a \includelineno includelineno.h but this isn't.
516 | //!
517 | //! This is a \htmlinclude htmlinclude.html but this isn't.
518 | //!
519 | //! This is a \verbinclude verbinclude.h but this isn't.
520 |
521 | class TestFilename2
522 | {
523 | };
524 |
525 | //! Commands that take one word as arguments:
526 | //!
527 | //! This is an \addtopage addtopage but this isn't.
528 | //!
529 | //! This is a \defgroup defgroup but this isn't.
530 | //!
531 | //! This is a \weakgroup wekgroup but this isn't.
532 | //!
533 | //! This is a \page page but this isn't.
534 | //!
535 | //! This is an \anchor anchor but this isn't.
536 | //!
537 | //! This is a \ref ref but this isn't.
538 | //!
539 | //! This is a \section section but this isn't.
540 | //!
541 | //! This is a \subsection subsection but this isn't.
542 |
543 | class TestWord2
544 | {
545 | };
546 |
547 | //! Special:
548 | //!
549 | //! \ingroup arg1 arg2 arg3 arg4
550 | //!
551 | //! \dotfile filename "This is a caption" but this isn't.
552 | //!
553 | //! \image jpg filename "This is a caption"
554 | //!
555 | //! \image jpg filename "This is a caption" size=100
556 |
557 | class TestSpecial
558 | {
559 | };
560 |
561 | //! End-of-line code.
562 | //!
563 | //! \fn void f();
564 | //!
565 | //! \var int x;
566 |
567 | /*!
568 | * \var int x;
569 | */
570 |
571 | /*! \var int x; */
572 |
573 |
574 | // ------------------------------------------------------------
575 | // Copy commands
576 |
577 | //! Test copy commands.
578 | class TestCopy
579 | {
580 | public:
581 | //! A function.
582 | TestFunction(int);
583 |
584 | //! \copydoc TestFunction()
585 | int TestFunction2(int parameter);
586 |
587 | //! \copydoc TestFunction(int)
588 | int TestFunction3(int parameter);
589 |
590 |
591 | //! Function with types with spaces.
592 | int TestUnsignedLong(unsigned long parameter);
593 |
594 | //! \copydoc TestUnsignedLong(unsigned long)
595 | int TestUnsignedLong2(unsigned long parameter);
596 |
597 | //! \copydoc TestUnsignedLong(unsigned long) And some more text.
598 | int TestUnsignedLong3(unsigned long parameter);
599 |
600 | //! \copydoc TestUnsignedLong(unsigned long) \return a value.
601 | int TestUnsignedLong4(unsigned long parameter);
602 | };
603 |
604 |
605 |
606 | // normal.h ends here
607 |
--------------------------------------------------------------------------------
/test/files/markdown.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:markdown.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:Example C++ code with Doxygen markdown-style blocks.
27 | »
28 | «m:// »«x:Code:
29 | »
30 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This comment contains an implicit verbatim block.
31 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
32 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:This is verbatim
33 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: And this too.
34 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
35 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Just check so that verbatim blocks aren't treated as code:
36 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
37 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:if (true)
38 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
39 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: ...
40 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
41 | »»»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
42 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! End of comment.
43 | »»
44 | «k:class» «t:TestVerbatimImplicit»
45 | {
46 | «k:public»:
47 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:!
48 | » «:highlight-doxygen-comment: *
49 | » «:highlight-doxygen-comment: * The following is not seen as a verbatim block by Doxygen
50 | » «:highlight-doxygen-comment: *
51 | » «:highlight-doxygen-comment: * Zero
52 | » «:highlight-doxygen-comment: * One
53 | » «:highlight-doxygen-comment: * Two
54 | » «:highlight-doxygen-comment: * Three
55 | » «:highlight-doxygen-comment: * Four
56 | » «:highlight-doxygen-comment: * Five
57 | » «:highlight-doxygen-comment: * Six
58 | » «:highlight-doxygen-comment: * Seven
59 | » «:highlight-doxygen-comment: * Eight
60 | » «:highlight-doxygen-comment: *
61 | » «:highlight-doxygen-comment: * Part of the following is seen as verbatim block by Doxygen.
62 | » «:highlight-doxygen-comment: *
63 | » «:highlight-doxygen-comment: * «:highlight-doxygen-code-block: Eight
64 | »» «:highlight-doxygen-comment: * «:highlight-doxygen-code-block: Seven
65 | »» «:highlight-doxygen-comment: * «:highlight-doxygen-code-block: Six
66 | »» «:highlight-doxygen-comment: * «:highlight-doxygen-code-block: Five
67 | »» «:highlight-doxygen-comment: * «:highlight-doxygen-code-block:Four <---- Last line of the block
68 | »» «:highlight-doxygen-comment: * Three
69 | » «:highlight-doxygen-comment: * Two
70 | » «:highlight-doxygen-comment: * One
71 | » «:highlight-doxygen-comment: * Zero
72 | » «:highlight-doxygen-comment: *
73 | » «:highlight-doxygen-comment: * This is more plain text.
74 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
75 | » «t:void» «f:TestVariableIndentation»();
76 |
77 | «m:// »«x:The following two test shows that the block must be indented four
78 | » «m:// »«x:spaces more than the surrounding text, even if the surrounding
79 | » «m:// »«x:text starts one column to the right due to the "!" sign.
80 | »
81 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! Test initial block.
82 | » «:highlight-doxygen-comment: *
83 | » «:highlight-doxygen-comment: * Four spaces. Not seen as block by Doxygen.
84 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
85 | » «t:void» «f:TestInitialBlock4»();
86 |
87 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! Test initial block.
88 | » «:highlight-doxygen-comment: *
89 | » «:highlight-doxygen-comment: * «:highlight-doxygen-code-block:Five spaces. Seen as block by Doxygen.
90 | »» «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
91 | » «t:void» «f:TestInitialBlock5»();
92 |
93 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! Test block at the end.
94 | » «:highlight-doxygen-comment: *
95 | » «:highlight-doxygen-comment: * This is plain text.
96 | » «:highlight-doxygen-comment: *
97 | » «:highlight-doxygen-comment: * «:highlight-doxygen-code-block:This is a block
98 | »» «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
99 | » «t:void» «f:TestBlockAtTheEnd»();
100 |
101 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! Test if block can start without an empty line. (No, they can't.)
102 | » «:highlight-doxygen-comment: *
103 | » «:highlight-doxygen-comment: * Text
104 | » «:highlight-doxygen-comment: * Maybe block
105 | » «:highlight-doxygen-comment: *
106 | » «:highlight-doxygen-comment: * Text2
107 | » «:highlight-doxygen-comment: * Maybe block
108 | » «:highlight-doxygen-comment: * Text3
109 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
110 | » «t:void» «f:TestTightBlock»();
111 |
112 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! Test if blocks indented a bit at a time is seen as a block.
113 | » «:highlight-doxygen-comment: *
114 | » «:highlight-doxygen-comment: * Text1
115 | » «:highlight-doxygen-comment: *
116 | » «:highlight-doxygen-comment: * Text2
117 | » «:highlight-doxygen-comment: *
118 | » «:highlight-doxygen-comment: * Text3
119 | » «:highlight-doxygen-comment: *
120 | » «:highlight-doxygen-comment: * «:highlight-doxygen-code-block:Text4 <- Indented with 4 spaces, seen as block.
121 | »» «:highlight-doxygen-comment: *
122 | » «:highlight-doxygen-comment: * Text5
123 | » «:highlight-doxygen-comment: *
124 | » «:highlight-doxygen-comment: * Text6
125 | » «:highlight-doxygen-comment: *
126 | » «:highlight-doxygen-comment: * Text1
127 | » «:highlight-doxygen-comment: *
128 | » «:highlight-doxygen-comment: * Text2
129 | » «:highlight-doxygen-comment: *
130 | » «:highlight-doxygen-comment: * Text3
131 | » «:highlight-doxygen-comment: *
132 | » «:highlight-doxygen-comment: * «:highlight-doxygen-code-block:Text4 <- Indented with 4 spaces, seen as block.
133 | »» «:highlight-doxygen-comment: * Text5 <- Not part of block.
134 | » «:highlight-doxygen-comment: * Text6
135 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
136 | » «t:void» «f:TestStaggering»();
137 |
138 | «m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:!
139 | » «:highlight-doxygen-comment: * Test if a block can start with a more indented line.
140 | » «:highlight-doxygen-comment: *
141 | » «:highlight-doxygen-comment: * «:highlight-doxygen-code-block: Text8
142 | »» «:highlight-doxygen-comment: * «:highlight-doxygen-code-block:Text7
143 | »» «:highlight-doxygen-comment: *
144 | » «:highlight-doxygen-comment: * Text after.
145 | » «:highlight-doxygen-comment: */»»«:highlight-doxygen-comment:
146 | » «t:void» «f:TestMoreIndented»();
147 |
148 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
149 | »» «t:void» «f:TestEmptySlashSlashComment»();
150 |
151 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test code block at end of C++ comment.
152 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
153 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:if (test)
154 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
155 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block: ..
156 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
157 | »»» «t:void» «f:TestEndOfSlashSlashComment»();
158 |
159 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test «t:MarkDown» code blocks after non-straight left margin.
160 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
161 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Alpha
162 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Beta
163 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Gamma
164 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
165 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Is this a code block? (NO, according to Doxygen)
166 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
167 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Alpha
168 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Beta
169 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Gamma
170 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
171 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:Is this a code block? (YES, according to Doxygen)
172 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
173 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Alpha
174 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Beta
175 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Gamma
176 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
177 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:Is this a code block? (YES, according to Doxygen)
178 | »»» «t:void» «f:TestNonStraightMargin»();
179 |
180 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test code block with empty lines
181 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
182 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Empty line (no spaces):
183 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
184 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:if (test)
185 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
186 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
187 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
188 | »»» «t:void» «f:TestEmptyLinesInCodeBlock»();
189 |
190 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test explicit code blocks.
191 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
192 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Explicit code block:
193 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
194 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
195 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» (test)
196 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
197 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
198 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
199 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
200 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
201 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Explicit code block after markdown block:
202 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
203 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:Is this a code block? (YES, according to Doxygen)
204 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
205 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
206 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» (test)
207 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
208 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
209 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
210 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
211 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
212 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Explicit code block before markdown block, same indentation:
213 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
214 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
215 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» (test)
216 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
217 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
218 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
219 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
220 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
221 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Is this a code block? (NO, according to Doxygen)
222 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
223 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Explicit code block before markdown block, more indentation:
224 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
225 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
226 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» (test)
227 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
228 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
229 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
230 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
231 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
232 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:Is this a code block? (YES, according to Doxygen)
233 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
234 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Explicit code block before markdown block, commands indented:
235 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
236 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:code»
237 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:«k:if» (test)
238 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:{
239 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
240 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-code-block:}
241 | »»» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcode»
242 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
243 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Is this a code block? (NO, according to Doxygen)
244 | »» «t:void» «f:TestMixExplicitAndImplicit»();
245 | };
246 |
247 | «m:// »«x:markdown.h ends here
248 | »
--------------------------------------------------------------------------------
/test/files/normal.h.faceup:
--------------------------------------------------------------------------------
1 | «m:// »«x:normal.h --- Example C++ code with Doxygen comments.
2 | »
3 | «m:// »«x:Commentary:
4 | »
5 | «m:// »«x:Copyright (C) 2018 Anders Lindgren
6 | »
7 | «m:// »«x:Author: Anders Lindgren
8 | »
9 | «m:// »«x:This file is part of the `highlight-doxygen' package.
10 | »
11 | «m:// »«x:This program is free software; you can redistribute it and/or modify
12 | »«m:// »«x:it under the terms of the GNU General Public License as published by
13 | »«m:// »«x:the Free Software Foundation, either version 3 of the License, or
14 | »«m:// »«x:(at your option) any later version.
15 | »
16 | «m:// »«x:This program is distributed in the hope that it will be useful,
17 | »«m:// »«x:but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | »«m:// »«x:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | »«m:// »«x:GNU General Public License for more details.
20 | »
21 | «m:// »«x:You should have received a copy of the GNU General Public License
22 | »«m:// »«x:along with this program. If not, see .
23 | »
24 | «m:// »«x:Commentary:
25 | »
26 | «m:// »«x:Example C++ code with Doxygen comments demonstrates a number of
27 | »«m:// »«x:known problems with the `highlight-doxygen' package.
28 | »
29 | «m:// »«x:Code:
30 | »
31 | «m:// »«x:This file contains most, if not all, doxygen commands.
32 | »«m://»«x:
33 | »«m:// »«x:The main purpouse of this file is for regression testing of the
34 | »«m:// »«x:Emacs package "highlight-doxygen".
35 | »«m://»«x:
36 | »«m:// »«x:Doxygen comments with code examples are in separate files.
37 | »
38 | «m:// »«x:Conventions:
39 | »«m://»«x:
40 | »«m:// »«x:Constructs defined in this file are named TestXxx.
41 | »«m://»«x:
42 | »«m:// »«x:Constructs defined using doxygen commands like "\class" are named
43 | »«m:// »«x:FakeXxx or fakexxxx.
44 | »
45 |
46 | «m:// »«x:------------------------------------------------------------
47 | »«m:// »«x:Commands that define construct somewhere else
48 | »«m://»«x:
49 | »
50 | «m:// »«x:TODO: The [header-file] [header-name] syntax in all of the following:
51 | »
52 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «:highlight-doxygen-type:fakeclass»
53 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
54 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake class.
55 | »»«:highlight-doxygen-comment:
56 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClass»»
57 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
58 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake class.
59 | »»«:highlight-doxygen-comment:
60 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:enum» «:highlight-doxygen-type:fakeenum»
61 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
62 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake enum.
63 | »»«:highlight-doxygen-comment:
64 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:enum» «t:«:highlight-doxygen-type:FakeEnum»»
65 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
66 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake enum.
67 | »»«:highlight-doxygen-comment:
68 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:interface» «:highlight-doxygen-type:fakeinterface»
69 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
70 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake interface.
71 | »»«:highlight-doxygen-comment:
72 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:interface» «t:«:highlight-doxygen-type:FakeInterface»»
73 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
74 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake interface.
75 | »»«:highlight-doxygen-comment:
76 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:namespace» «:highlight-doxygen-namespace:fakenamespace»
77 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
78 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake namespace.
79 | »»«:highlight-doxygen-comment:
80 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:namespace» «t:«:highlight-doxygen-namespace:FakeNamespace»»
81 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
82 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake namespace.
83 | »»«:highlight-doxygen-comment:
84 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:namespace» «t:fakeparent»::«:highlight-doxygen-namespace:fakenamespace»
85 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
86 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake namespace.
87 | »»«:highlight-doxygen-comment:
88 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:namespace» «t:«t:FakeParent»»::«t:«:highlight-doxygen-namespace:FakeNamespace»»
89 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
90 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake namespace.
91 | »»«:highlight-doxygen-comment:
92 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:struct» «:highlight-doxygen-type:fakestruct»
93 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
94 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake struct.
95 | »»«:highlight-doxygen-comment:
96 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:struct» «t:«:highlight-doxygen-type:FakeStruct»»
97 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
98 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake struct.
99 | »»«:highlight-doxygen-comment:
100 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:union» «:highlight-doxygen-type:fakeunion»
101 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
102 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake union.
103 | »»«:highlight-doxygen-comment:
104 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:union» «t:«:highlight-doxygen-type:FakeUnion»»
105 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
106 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake union.
107 | »»
108 | «m:// »«x:Note: Objective-C.
109 | »
110 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:category» fakecategory
111 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
112 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake category.
113 | »»«:highlight-doxygen-comment:
114 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:category» «t:FakeCategory»
115 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
116 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake category.
117 | »»«:highlight-doxygen-comment:
118 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:protocol» «:highlight-doxygen-type:fakeprotocol»
119 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
120 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake protocol.
121 | »»«:highlight-doxygen-comment:
122 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:protocol» «t:«:highlight-doxygen-type:FakeProtocol»»
123 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
124 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake protocol.
125 | »»
126 |
127 |
128 | «m:// »«x:--------------------
129 | »«m:// »«x:Class
130 | »«m://»«x:
131 | »
132 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class for testing "related" etc.
133 | »»«k:class» «t:TypeClass»
134 | {
135 | };
136 |
137 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! A related function. \«:highlight-doxygen-command:relates» «t:«:highlight-doxygen-type:TypeClass»».
138 | »»«t:void» «f:TestRelates»(«t:void»);
139 |
140 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a namespace.
141 | »»«k:namespace» «c:TestNamespace»
142 | {
143 | }
144 |
145 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a union.
146 | »»«k:union» «t:TestUnion»
147 | {
148 | };
149 |
150 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an enum.
151 | »»«k:enum» «t:TypeEnum»
152 | {
153 | };
154 |
155 |
156 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Template class.
157 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
158 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:tparam» «:highlight-doxygen-variable:arraysize» size of array.
159 | »»«k:template»<«t:N» «v:arraysize»>
160 | «k:class» «t:TestTemplateClass»
161 | {
162 | «t:int» «v:arr»[arraysize];
163 | };
164 |
165 |
166 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Function that throws.
167 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
168 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:throw» «t:«:highlight-doxygen-exception:TestException»»
169 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:throw» «:highlight-doxygen-exception:Simple»
170 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:throw» «:highlight-doxygen-exception:lowercase»
171 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:throw» «t:Qualified»::«:highlight-doxygen-exception:Tip»
172 | »»«t:void» «f:TestThrows»() «k:throw» TestException;
173 |
174 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Another function that throws.
175 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
176 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:throw» «t:std»::«:highlight-doxygen-exception:out_of_range».
177 | »»«t:void» «f:TestThrows2»() «k:throw» «c:std»::out_of_range;
178 |
179 | «m:// »«x:--------------------
180 | »«m:// »«x:section-label
181 | »«m://»«x:
182 | »
183 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:if» «:highlight-doxygen-section-label:alabel»
184 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the "this" part.
185 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:elseif» «:highlight-doxygen-section-label:alabel»
186 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the "else" part.
187 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endif»
188 | »»
189 | «t:void» «f:TestSectionLabel»();
190 |
191 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:ifnot» «:highlight-doxygen-section-label:alabel»
192 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the "this" part.
193 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:elseif» «:highlight-doxygen-section-label:alabel»
194 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is the "else" part.
195 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endif»
196 | »»
197 | «t:void» «f:TestSectionLabel2»();
198 |
199 |
200 | «m:// »«x:--------------------
201 | »«m:// »«x:Groups
202 | »«m://»«x:
203 | »
204 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:defgroup» «:highlight-doxygen-group:group1» This is a group title.
205 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a group body.
206 | »»«:highlight-doxygen-comment:
207 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:addtogroup» «:highlight-doxygen-group:group1»
208 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! More group body.
209 | »»«:highlight-doxygen-comment:
210 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:weakgroup» «:highlight-doxygen-group:my_weak_group»
211 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a weak group.
212 | »»«:highlight-doxygen-comment:
213 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:ingroup» «:highlight-doxygen-group:group1»
214 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is in group1.
215 | »»
216 | «t:void» «f:TestIngroup»(«t:void»);
217 |
218 | «m:// »«x:TODO: Add support for specifying multiple groups.
219 | »
220 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:ingroup» «:highlight-doxygen-group:group1» my_weak_group
221 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is in group1 and my_weak_group.
222 | »»
223 | «t:void» «f:TestIngroup2»(«t:void»);
224 |
225 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dir» «:highlight-doxygen-filename:This/is/a/dir»
226 | »»
227 | «t:void» «f:TestDir»(«t:void»);
228 |
229 | «m:// »«x:TODO: If Doxygen can handle this, ensure we can too.
230 | »
231 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dir» "This is a path with spaces"
232 | »»
233 | «t:void» «f:TestDir2»(«t:void»);
234 |
235 | «m:// »«x:TODO: Check how Doxygen handle this.
236 | »
237 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dir» «:highlight-doxygen-filename:a_dir» This is not a dir.
238 | »»
239 | «t:void» «f:TestDir3»(«t:void»);
240 |
241 | «m:// »«x:--------------------
242 | »«m:// »«x:With filename arguments.
243 | »
244 | «m:// »«x:Syntax:
245 | »«m://»«x:
246 | »«m:// »«x:\class name [] []
247 | »
248 |
249 | «m:// »«x:Note: The "." isn't written in verbatim, as that produces a link.
250 | »
251 | «m:// »«x:Conclusion: can be foo.h or "foo.h".
252 | »
253 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNameP»» other.h
254 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with other dot h
255 | »»«:highlight-doxygen-comment:
256 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNameQ»» "other.h"
257 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with "other dot h"
258 | »»«:highlight-doxygen-comment:
259 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNamePP»» other.h sub/other.h
260 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with other dot h sub/other dot h
261 | »»«:highlight-doxygen-comment:
262 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNamePQ»» other.h "sub/other.h"
263 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with other dot h "sub/other dot h".
264 | »»«:highlight-doxygen-comment:
265 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNamePS»» other.h
266 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with other dot h \.
267 | »»«:highlight-doxygen-comment:
268 | »«m:«:highlight-doxygen-comment:/**»»«x:«:highlight-doxygen-comment:
269 | * \«:highlight-doxygen-command:a» «:highlight-doxygen-variable:arg»
270 | */»»«:highlight-doxygen-comment:
271 | »
272 | «m:// »«x:Note: The following doesn't seem to work in doxygen.
273 | »«m://»«x:
274 | »«m:// »«x:The documentation specifies:
275 | »«m://»«x:
276 | »«m:// »«x:\class name [] []
277 | »«m://»«x:
278 | »«m:// »«x:I guess that the documentation should read:
279 | »«m://»«x:
280 | »«m:// »«x:\class name [ []]
281 | »
282 | «p:#if» 0
283 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNameSubP»» sub/other.h
284 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with sub/other dot h.
285 | »»«:highlight-doxygen-comment:
286 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNameSubQ»» "sub/other.h"
287 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with "sub/other dot h".
288 | »»
289 | «m:// »«x:This fails badly, it generates "#include <<>".
290 | »
291 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNameS»»
292 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with \
293 | »»«:highlight-doxygen-comment:
294 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:class» «t:«:highlight-doxygen-type:FakeClassNameSubS»»
295 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Class with \.
296 | »»«p:#endif»
297 |
298 |
299 | «m:// »«x:TODO: This is another animal than the above.
300 | »
301 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:exception» «:highlight-doxygen-exception:fakeexception»
302 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
303 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake exception.
304 | »»«:highlight-doxygen-comment:
305 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:exception» «t:«:highlight-doxygen-exception:FakeException»»
306 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
307 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a fake exception.
308 | »»«:highlight-doxygen-comment:
309 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:throw» «:highlight-doxygen-exception:throw» but this isn't.
310 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
311 | »»
312 |
313 | «m:// »«x:------------------------------------------------------------
314 | »«m:// »«x:Commands that define constructs in the file
315 | »«m://»«x:
316 | »
317 | «m:// »«x:Place this is a comment OF something.
318 | »
319 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Link to the other.h header file.
320 | »»«:highlight-doxygen-comment:
321 |
322 |
323 | »«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Commands that take a variable as argument.
324 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
325 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! TODO: param
326 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
327 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:a» «:highlight-doxygen-variable:parameter» but this isn't.
328 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
329 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! TODO: Is this really a variable?
330 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
331 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is \«:highlight-doxygen-command:relates» «:highlight-doxygen-type:relates» but this doesn't.
332 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
333 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is \«:highlight-doxygen-command:relatesalso» «:highlight-doxygen-type:relatesalso» but this doesn't.
334 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
335 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:var» «:highlight-doxygen-code-block:«t:variable» «v:but» «k:this» isn«w:'»t.»
336 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
337 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:def» variable but this isn't.
338 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
339 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This \«:highlight-doxygen-command:implements» «t:«t:FakeClass»»::«t:«:highlight-doxygen-type:FakeFunction»».
340 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
341 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This \«:highlight-doxygen-command:implements» «t:fakeclass»::«:highlight-doxygen-type:fakefunction».
342 | »»
343 | «k:class» «t:TestVarArgs»
344 | {
345 | };
346 |
347 |
348 |
349 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test if the argument can be placed on another line.
350 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
351 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Highlighting for this is currently not supported.
352 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
353 | »»«k:class» «t:TestLineBreaks»
354 | {
355 | «k:public»:
356 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test if \«:highlight-doxygen-command:a»
357 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! my_argument can be on the next line.
358 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
359 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Check if there can be an empty line between the command and the
360 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! agument, like \«:highlight-doxygen-command:a»
361 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
362 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! arg2 here.
363 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
364 | »» «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Doxygen handles line breaks, but not empty lines.
365 | »» «t:void» «f:TestLineBreaks»(«t:int» «v:my_argument», «t:int» «v:arg2»)
366 | {
367 | }
368 | };
369 |
370 |
371 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Commands that take a function name as arguments:
372 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
373 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:retval» «:highlight-doxygen-code:function» but this isn't.
374 | »»
375 | «k:class» «t:TestRetval»
376 | {
377 | };
378 |
379 |
380 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Commands that take a "word" as argument:
381 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
382 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:a» «:highlight-doxygen-variable:parameter» but this isn't.
383 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
384 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:p» «:highlight-doxygen-variable:parameter» but this isn't.
385 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
386 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:anchor» anchor but this isn't.
387 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
388 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is \«:highlight-doxygen-command:b» «:highlight-doxygen-bold:bold» but this isn't.
389 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
390 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is \«:highlight-doxygen-command:c» «:highlight-doxygen-code:code» but this isn't.
391 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
392 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is \«:highlight-doxygen-command:e» «:highlight-doxygen-emphasize:emphasized» but this isn't.
393 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
394 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is \«:highlight-doxygen-command:em» «:highlight-doxygen-emphasize:emphasized» but this isn't.
395 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
396 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:retval» «:highlight-doxygen-code:ZERO» if \«:highlight-doxygen-command:p» «:highlight-doxygen-variable:parameter» is zero
397 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:retval» «:highlight-doxygen-code:NONZERO» if \«:highlight-doxygen-command:p» «:highlight-doxygen-variable:parameter» is non-zero
398 | »»
399 | «t:int» «f:TestWordFunction»(«t:int» «v:parameter»)
400 | {
401 | «k:if» (parameter > 0)
402 | {
403 | «k:return» NONZERO;
404 | }
405 | «k:else»
406 | {
407 | «k:return» ZERO;
408 | }
409 | }
410 |
411 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Parameter commands
412 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
413 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param» «:highlight-doxygen-variable:plain» a plain parameter
414 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param» [«:highlight-doxygen-direction:in»] «:highlight-doxygen-variable:x» an "in" parameter
415 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param» [«:highlight-doxygen-direction:out»] «:highlight-doxygen-variable:y» an "in" parameter
416 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param» [«:highlight-doxygen-direction:in»,«:highlight-doxygen-direction:out»] «:highlight-doxygen-variable:z» an "in" parameter
417 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
418 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Without whitespace:
419 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
420 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param»[«:highlight-doxygen-direction:in»]«:highlight-doxygen-variable:x» an "in" parameter
421 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param»[«:highlight-doxygen-direction:out»]«:highlight-doxygen-variable:y» an "in" parameter
422 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param»[«:highlight-doxygen-direction:in»,«:highlight-doxygen-direction:out»]«:highlight-doxygen-variable:z» an "in" parameter
423 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
424 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Partially written:
425 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
426 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:param»[«:highlight-doxygen-direction:in»]
427 | »»
428 | «t:void» «f:test»(«t:int» «v:plain», «t:int» «v:x», «t:int» «v:y», «t:int» «v:z»);
429 |
430 |
431 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:sa» «t:TestOptional»
432 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
433 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:sa» Paragraph with «t:TestOptional» reference.
434 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
435 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:sa» «:highlight-doxygen-link:http://www.some-company.com/a%20page.html»
436 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
437 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:sa» This is a paragraph with links like this one
438 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «:highlight-doxygen-link:http://www.some-company.com/a%20page.html» and
439 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! «f:function_like_this_one»().
440 | »»
441 | «k:class» «t:TestSeeAlso»
442 | {
443 | };
444 |
445 | «m:// »«x:TODO: link copydoc xrefitem if ifnot elseif
446 | »
447 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Commands that take an optional argument:
448 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
449 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! TODO: How?
450 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
451 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:cond»
452 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
453 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:cond» «:highlight-doxygen-section-label:argument»
454 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
455 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:cond» «:highlight-doxygen-section-label:argument1» argument2
456 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
457 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcond»
458 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
459 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcond»
460 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
461 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:endcond»
462 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
463 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dir»
464 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
465 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dir» «:highlight-doxygen-filename:argument»
466 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
467 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dir» «:highlight-doxygen-filename:argument1» argument2
468 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
469 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \~
470 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
471 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \~argument
472 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
473 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \~argument1 argument2
474 | »»
475 | «k:class» «t:TestOptional»
476 | {
477 | };
478 |
479 |
480 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:ref» «:highlight-doxygen-link:a_reference» but this isn't.
481 | »»
482 | «k:class» «t:TestReference»
483 | {
484 | };
485 |
486 |
487 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Testing filenames:
488 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
489 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» «:highlight-doxygen-filename:example» but this isn't.
490 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
491 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» «:highlight-doxygen-filename:example.cpp» but this isn't.
492 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
493 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» "example.cpp" but this isn't.
494 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
495 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» "a/path/to/an/example.cpp" but this isn't.
496 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
497 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» "a\«:highlight-doxygen-command:path»\«:highlight-doxygen-command:to»\«:highlight-doxygen-command:an»\«:highlight-doxygen-command:example».cpp" but this isn't.
498 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
499 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» "a path with spaces/example.cpp" but this isn't.
500 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
501 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» "a path with spaces\«:highlight-doxygen-command:example».cpp" but this isn't.
502 | »»
503 | «k:class» «t:TestFilename1»
504 | {
505 | };
506 |
507 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Commands that take a file name as arguments:
508 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
509 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:example» «:highlight-doxygen-filename:example.h» but this isn't.
510 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
511 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:dont» dont.h but this isn't.
512 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
513 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:dontinclude» «:highlight-doxygen-filename:dontinclude.h» but this isn't.
514 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
515 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:includelineno» «:highlight-doxygen-filename:includelineno.h» but this isn't.
516 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
517 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:htmlinclude» «:highlight-doxygen-filename:htmlinclude.html» but this isn't.
518 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
519 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:verbinclude» «:highlight-doxygen-filename:verbinclude.h» but this isn't.
520 | »»
521 | «k:class» «t:TestFilename2»
522 | {
523 | };
524 |
525 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Commands that take one word as arguments:
526 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
527 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:addtopage» addtopage but this isn't.
528 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
529 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:defgroup» «:highlight-doxygen-group:defgroup» but this isn't.
530 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
531 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:weakgroup» «:highlight-doxygen-group:wekgroup» but this isn't.
532 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
533 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:page» «:highlight-doxygen-label:page»«:highlight-doxygen-heading-2: but this isn't.»
534 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
535 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is an \«:highlight-doxygen-command:anchor» anchor but this isn't.
536 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
537 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:ref» «:highlight-doxygen-link:ref» but this isn't.
538 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
539 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:section» «:highlight-doxygen-label:section»«:highlight-doxygen-heading-2: but this isn't.»
540 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
541 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! This is a \«:highlight-doxygen-command:subsection» «:highlight-doxygen-label:subsection»«:highlight-doxygen-heading-3: but this isn't.»
542 | »»
543 | «k:class» «t:TestWord2»
544 | {
545 | };
546 |
547 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Special:
548 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
549 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:ingroup» «:highlight-doxygen-group:arg1» arg2 arg3 arg4
550 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
551 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:dotfile» «:highlight-doxygen-filename:filename» "This is a caption" but this isn't.
552 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
553 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:image» jpg filename "This is a caption"
554 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
555 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:image» jpg filename "This is a caption" size=100
556 | »»
557 | «k:class» «t:TestSpecial»
558 | {
559 | };
560 |
561 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! End-of-line code.
562 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
563 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:fn» «:highlight-doxygen-code-block:«t:void» »«f:«:highlight-doxygen-code-block:«f:f»»»«:highlight-doxygen-code-block:();»
564 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:!
565 | »»«m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:var» «:highlight-doxygen-code-block:«t:int» «v:x»;»
566 | »»«:highlight-doxygen-comment:
567 | »«m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:!
568 | * \«:highlight-doxygen-command:var» «:highlight-doxygen-code-block:«t:int» «v:x»;»
569 | */»»«:highlight-doxygen-comment:
570 |
571 | »«m:«:highlight-doxygen-comment:/*»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:var» «:highlight-doxygen-code-block:«t:int» «v:x»; */»»»«:highlight-doxygen-comment:
572 | »
573 |
574 | «m:// »«x:------------------------------------------------------------
575 | »«m:// »«x:Copy commands
576 | »
577 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Test copy commands.
578 | »»«k:class» «t:TestCopy»
579 | {
580 | «k:public»:
581 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! A function.
582 | »» TestFunction(«t:int»);
583 |
584 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:copydoc» «f:«:highlight-doxygen-code-block:TestFunction»»«:highlight-doxygen-code-block:()»
585 | »» «t:int» «f:TestFunction2»(«t:int» «v:parameter»);
586 |
587 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:copydoc» «:highlight-doxygen-code-block:TestFunction(«t:int»)»
588 | »» «t:int» «f:TestFunction3»(«t:int» «v:parameter»);
589 |
590 |
591 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! Function with types with spaces.
592 | »» «t:int» «f:TestUnsignedLong»(«t:unsigned» «t:long» «v:parameter»);
593 |
594 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:copydoc» «:highlight-doxygen-code-block:TestUnsignedLong(«t:unsigned» «t:long»)»
595 | »» «t:int» «f:TestUnsignedLong2»(«t:unsigned» «t:long» «v:parameter»);
596 |
597 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:copydoc» «:highlight-doxygen-code-block:TestUnsignedLong(«t:unsigned» «t:long»)» And some more text.
598 | »» «t:int» «f:TestUnsignedLong3»(«t:unsigned» «t:long» «v:parameter»);
599 |
600 | «m:«:highlight-doxygen-comment://»»«x:«:highlight-doxygen-comment:! \«:highlight-doxygen-command:copydoc» «:highlight-doxygen-code-block:TestUnsignedLong(«t:unsigned» «t:long»)» \«:highlight-doxygen-command:return» a value.
601 | »» «t:int» «f:TestUnsignedLong4»(«t:unsigned» «t:long» «v:parameter»);
602 | };
603 |
604 |
605 |
606 | «m:// »«x:normal.h ends here
607 | »
--------------------------------------------------------------------------------
/highlight-doxygen.el:
--------------------------------------------------------------------------------
1 | ;;; highlight-doxygen.el --- Highlight Doxygen comments
2 |
3 | ;; Copyright (C) 2016-2018 Anders Lindgren
4 |
5 | ;; Author: Anders Lindgren
6 | ;; Keywords: faces
7 | ;; Created: 2016-02-12
8 | ;; Version: 0.0.2
9 | ;; URL: https://github.com/Lindydancer/highlight-doxygen
10 |
11 | ;; This program is free software; you can redistribute it and/or modify
12 | ;; it under the terms of the GNU General Public License as published by
13 | ;; the Free Software Foundation, either version 3 of the License, or
14 | ;; (at your option) any later version.
15 |
16 | ;; This program is distributed in the hope that it will be useful,
17 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 | ;; GNU General Public License for more details.
20 |
21 | ;; You should have received a copy of the GNU General Public License
22 | ;; along with this program. If not, see .
23 |
24 | ;;; Commentary:
25 |
26 | ;; Advanced highlighting package for Doxygen comments.
27 | ;;
28 | ;; In addition to highlighting Doxygen commands and their arguments,
29 | ;; entire Doxygen comment are highlighted, making them stand out
30 | ;; compared to other comments. In addition, and code blocks are
31 | ;; highlighted according to the language they are written in.
32 |
33 | ;; Usage:
34 | ;;
35 | ;; This package provide two minor modes, `highlight-doxygen-mode' and
36 | ;; `highlight-doxygen-global-mode'.
37 | ;;
38 | ;; Can enable `highlight-doxygen-mode' from the hook of a mode.
39 | ;;
40 | ;; Alternatively, you can enable the minor mode for all major modes
41 | ;; specified in `highlight-doxygen-modes'. Typically, this is done by
42 | ;; placing the following in a suitable init file:
43 | ;;
44 | ;; (highlight-doxygen-global-mode 1)
45 |
46 | ;; What is highlighted:
47 | ;;
48 | ;; * The full Doxygen comment is highlighted with a different
49 | ;; background color, to make them stand out compared to normal code
50 | ;; other comments.
51 | ;;
52 | ;; * Doxygen commands and their arguments are highlighted. The
53 | ;; arguments are highlighted according to the signature of the
54 | ;; commands. For example, the argument to the `\a' command is
55 | ;; highlighted as a variable.
56 | ;;
57 | ;; * Code blocks are highlighted using the Emacs highlighting rules
58 | ;; for the language they are written in. In addition, the
59 | ;; background is changed to make the code block stand out.
60 | ;;
61 | ;; * Customization friendly. This package define a number of custom
62 | ;; faces that can be customized to fine tune the appearance if this
63 | ;; package. The default value of all defined faces inherit from
64 | ;; standard Emacs faces, which mean that customizations done by the
65 | ;; user or themes are automatically used.
66 |
67 | ;; Code blocks:
68 | ;;
69 | ;; A code block is specified using a pair of Doxygen commands like
70 | ;; `\code' and `\endcode' or `\dot' and `\enddot'.
71 | ;;
72 | ;; Code blocks are syntax highlighted using the major mode they are
73 | ;; written in. The major mode is selected as follows:
74 | ;;
75 | ;; * If the `\code{.ext}' construct is used, the major mode associated
76 | ;; with extension `.ext' is used.
77 | ;;
78 | ;; * For `\dot', `\msc', and `\startuml' is used, the extensions
79 | ;; `.dot', `.msc', and `.plantuml' are used, respectively.
80 | ;;
81 | ;; * For `\code' blocks that does not specify an extension, the major
82 | ;; mode of the buffer is used.
83 |
84 | ;;; Code:
85 |
86 | ;; Internal comments starts here.
87 | ;;
88 | ;; (Nothing below the "Code:" comment is included in the generated
89 | ;; README.md file.)
90 |
91 | ;; Known problems:
92 | ;;
93 | ;; * When there is space between two C-style Doxygen comments, it
94 | ;; should not be highlighted.
95 | ;;
96 | ;; > /*!
97 | ;; > * A comment
98 | ;; > */
99 | ;; > <-- Don't highlight here.
100 | ;; > /*!
101 | ;; > * A comment
102 | ;; > */
103 | ;;
104 | ;; * A \code without a matching \endcode should not pick up someone
105 | ;; elses \endcode, that would highlight too much.
106 | ;;
107 | ;; * Empty lines in Doxygen comments disrupt the "block" highlighting.
108 | ;;
109 | ;; > /* Title <-- The block starts on the "/".
110 | ;; > <-- Starts at the beginning of the line.
111 | ;; > */ <-- Starts at the space before the "*".
112 | ;;
113 | ;; * Empty lines in code disrupt the "code block" highlighting.
114 | ;;
115 | ;; > //! \code
116 | ;; > //! if (true)
117 | ;; > //! {
118 | ;; > //! <-- This line is not highlighted as code
119 | ;; > //! }
120 | ;; > //! \endcode
121 | ;;
122 | ;; * Verbatim blocks
123 | ;;
124 | ;; In Doxygen, everything between \verbatim and \endverbatim is
125 | ;; included, exactly as written. This include things like comment
126 | ;; start characters. Currently, verbatim blocks are highlighted like
127 | ;; code blocks.
128 | ;;
129 | ;; Also, when the \verbatim and \endverbatim is placed in different
130 | ;; comments, any code between them is included in the comment. This
131 | ;; package highlight one Doxygen comment block at a time; with this
132 | ;; system in place in it not possible to highlight blocks across
133 | ;; Doxygen comments.
134 |
135 | ;; Notes on individual commands:
136 | ;;
137 | ;; The Doxygen documentation says that "a", "e", and "em" are the
138 | ;; same. However, it also says that "a" should be used to highlights
139 | ;; parameters. This package highlight the argument of "a" as a
140 | ;; variable (to match the parameter list) and the argument to "e" and
141 | ;; "em" in a different way, by default in italics.
142 | ;;
143 | ;; The commands "sa" and "see" start a new paragraph that could
144 | ;; contains references and links. There are example code where the
145 | ;; paragraphs only contain one word, a reference, but in the general
146 | ;; case it's impossible to know that this really is the case.
147 |
148 | ;; Future ideas:
149 | ;;
150 | ;; This section contains "wild ideas" that aren't in the current
151 | ;; implementation plan.
152 | ;;
153 | ;; ## Hide "\a" in "\a var"?
154 | ;;
155 | ;; This would make the code more readable. However, it would also make
156 | ;; it easy to accidentally write badly formatted or too long lines.
157 | ;;
158 | ;; ## Highlight some commands differently
159 | ;;
160 | ;; For example, "\attention" "\warning" "\todo" "\bug" could be
161 | ;; highlighted in (a face inheriting from) the warning face.
162 | ;;
163 | ;; ## Support more commands
164 | ;;
165 | ;; - "\def foo" -- Highlight "foo" as a variable. "\def foo(x,y)" --
166 | ;; Highlight "foo" as a function and the parameters as variables.
167 | ;; Note: I failed to include \def:ed macros in the generated Doxygen
168 | ;; output, so it's hard to know if the commands are used as
169 | ;; intended.
170 | ;;
171 | ;; ## Highlight across lines
172 | ;;
173 | ;; Today, the argument to commands like "\a" must be place on the same
174 | ;; line as the command. However, Doxygen supports placing the
175 | ;; argument on the next line. Technically, one way to implement this
176 | ;; is to only match "\a" using the main regexp and replace the face
177 | ;; expression with a call to a function that highlights the next word
178 | ;; (possibly skipping comment start characters, stars etc, and then
179 | ;; return nil (so that font-lock doesn't add anther face on top of the
180 | ;; one we just used ourselves).
181 | ;;
182 | ;; ## Highlight HTML constructs
183 | ;;
184 | ;; Highlight HTML constructs like Multiple words. Tricky to
185 | ;; handle constructs that spam multiple lines and nested constructs.
186 | ;;
187 | ;; ## Clickable links
188 | ;;
189 | ;; Make it possible to click on "http"-like links. (Check if there
190 | ;; exist a package for this already.)
191 | ;;
192 | ;; ## Support for formats like JavaDoc
193 | ;;
194 | ;; Currently, this package only support Doxygen. However, a number of
195 | ;; similar formats exists, like JavaDoc. Maybe they should be
196 | ;; supported as well.
197 | ;;
198 | ;; ## Edit code block
199 | ;;
200 | ;; Add support to edit code blocks in a separate buffer, like in org
201 | ;; mode.
202 |
203 | ;; Implementation:
204 | ;;
205 | ;; Extra properties:
206 | ;;
207 | ;; In addition to faces, this package sets a number of text properties
208 | ;; on Doxygen comments.
209 | ;;
210 | ;; - `highlight-doxygen-code' -- Set on all lines in an actual code
211 | ;; block. This is used to prevent Doxygen font-lock rules from
212 | ;; being applied inside code blocks.
213 | ;;
214 | ;; - `highlight-doxygen-ignore' -- Set on all lines in a code block
215 | ;; from the code/verbatim Doxygen command to the endcode/endverbatim
216 | ;; command. This is used to prevent the markdown code rule from
217 | ;; inspecting the surrounding Doxygen commands, as they often are
218 | ;; heavily indented
219 |
220 | ;; Doxygen information:
221 | ;;
222 | ;; https://www.stack.nl/~dimitri/Doxygen/manual/commands.html
223 | ;;
224 | ;; A MarkDown-style code block needs four spaces more than the
225 | ;; surrounding text. When the indentation gets lets than four spaces,
226 | ;; the code block ends, even when in the middle of consecutive lines.
227 | ;;
228 | ;; From the Doxygen manual:
229 | ;;
230 | ;; > Some commands have one or more arguments. Each argument has a
231 | ;; > certain range:
232 | ;; >
233 | ;; > If braces are used the argument is a single word.
234 | ;; >
235 | ;; > If (round) braces are used the argument extends until the end of
236 | ;; > the line on which the command was found.
237 | ;; >
238 | ;; > If {curly} braces are used the argument extends until the next
239 | ;; > paragraph. Paragraphs are delimited by a blank line or by a section
240 | ;; > indicator.
241 |
242 | ;; -------------------------------------------------------------------
243 | ;; Dependencies
244 | ;;
245 |
246 | ;; For the faces.
247 | (require 'outline)
248 |
249 | ;; Don't warn for using these dynamically bound variables, see
250 | ;; `font-lock-extend-region-functions'.
251 | (eval-when-compile
252 | (defvar font-lock-beg)
253 | (defvar font-lock-end))
254 |
255 |
256 | ;; -------------------------------------------------------------------
257 | ;; Variables, faces, and customization support
258 | ;;
259 |
260 | (defgroup highlight-doxygen nil
261 | "Highlight Doxygen comments."
262 | :group 'faces)
263 |
264 |
265 | (defface highlight-doxygen-comment
266 | '((((background light)) :inherit font-lock-doc-face :background "grey95")
267 | (((background dark)) :inherit font-lock-doc-face :background "grey30"))
268 | "The face used for Doxygen comment blocks."
269 | :group 'highlight-doxygen)
270 |
271 |
272 | (defface highlight-doxygen-code-block
273 | '((((background light)) :background "grey85")
274 | (((background dark)) :background "grey40"))
275 | "The face used to mark a code block."
276 | :group 'highlight-doxygen)
277 |
278 |
279 | (defface highlight-doxygen-command
280 | '((t :inherit font-lock-constant-face))
281 | "The face used to mark Doxygen commands."
282 | :group 'highlight-doxygen)
283 |
284 |
285 | (defcustom highlight-doxygen-modes
286 | '(c-mode
287 | c++-mode
288 | objc-mode)
289 | "List of major modes where Highlight Doxygen Global mode should be enabled.
290 |
291 | The mode is enabled for buffers whose major mode is a member of
292 | this list, or is derived from a member in the list."
293 | :group 'highlight-doxygen
294 | :type '(repeat symbol))
295 |
296 |
297 | (defcustom highlight-doxygen-commend-start-regexp
298 | "\\(/\\*\\(!\\|\\*[^*]\\)\\|//\\(!\\|/[^/\n]\\)\\)"
299 | "Regexp matching the beginning of a Doxygen comment."
300 | :group 'highlight-doxygen
301 | :type 'regexp)
302 |
303 |
304 | (defcustom highlight-doxygen-triple-slash-comment-regexp "///"
305 | "Regexp to match triple slash comments."
306 | :group 'highlight-doxygen
307 | :type 'regexp)
308 |
309 |
310 | (defcustom highlight-doxygen-ignore-triple-slash-comments nil
311 | "When non-nil, triple slash comments are ignored."
312 | :group 'highlight-doxygen
313 | :type 'boolean)
314 |
315 |
316 | ;; -------------------------------------------------------------------
317 | ;; Helper functions.
318 | ;;
319 |
320 | (defun highlight-doxygen-replace-in-sexp (new old sexp)
321 | "Return a copy of SEXP where OLD has been replaced by NEW.
322 |
323 | If OLD does not occur in SEXP, SEXP is returned."
324 | (cond ((eq old sexp) new)
325 | ((consp sexp)
326 | (let* ((lhs0 (car sexp))
327 | (rhs0 (cdr sexp))
328 | (lhs (highlight-doxygen-replace-in-sexp new old lhs0))
329 | (rhs (highlight-doxygen-replace-in-sexp new old rhs0)))
330 | (if (and (eq lhs lhs0)
331 | (eq rhs rhs0))
332 | sexp
333 | (cons lhs rhs))))
334 | (t sexp)))
335 |
336 |
337 | ;; -------------------------------------------------------------------
338 | ;; Code block highlighter.
339 | ;;
340 |
341 | (defun highlight-doxygen-next-property-change (pos property)
342 | "Next position after POS where PROPERTY change.
343 |
344 | If POS is nil, also include `point-min' in the search.
345 | If last character contains the property, return `point-max'."
346 | (if (equal pos (point-max))
347 | ;; Last search returned `point-max'. There is no more to search
348 | ;; for.
349 | nil
350 | (if (and (null pos)
351 | (get-text-property (point-min) property))
352 | ;; `pos' is `nil' and the character at `point-min' contains
353 | ;; the property, return `point-min'.
354 | (point-min)
355 | (unless pos
356 | ;; Start from the beginning.
357 | (setq pos (point-min)))
358 | ;; Do a normal search. Compensate for that
359 | ;; `next-single-property-change' does not include the end of the
360 | ;; buffer, even when the property reach it.
361 | (let ((res (next-single-property-change pos property)))
362 | (if (and (not res) ; No more found.
363 | (not (equal pos (point-max))) ; Not already at the end.
364 | (not (equal (point-min) (point-max))) ; Not an empty buffer.
365 | (get-text-property (- (point-max) 1) property))
366 | ;; If the property goes all the way to the end of the
367 | ;; buffer, return `point-max'.
368 | (point-max)
369 | res)))))
370 |
371 |
372 | ;; TODO: Check if face properties on newline are handled properly.
373 | (defun highlight-doxygen-code-block (start end &optional mode)
374 | "Highlight block between START and END as code.
375 |
376 | MODE determined which major mode should be used to highlight the
377 | block.
378 |
379 | When MODE is a string, it should be on the form of a file
380 | extension, and the major mode associated with the file extension
381 | is used. When a function, that function is called to set the
382 | major mode. When nil, the block is not highlighted."
383 | ;; ----------
384 | ;; Mark the code block so that the other rules doesn't overwrite it.
385 |
386 | ;; TODO: As other rules use this, move it to the function that
387 | ;; handle code rule.
388 | (add-text-properties start end '(highlight-doxygen-code t))
389 | ;; ----------
390 | ;; Find start column
391 | (let (column)
392 | (save-excursion
393 | (goto-char start)
394 | (while (< (point) end)
395 | (let ((indentation (highlight-doxygen-current-indentation)))
396 | (when indentation
397 | (when (or (null column)
398 | (< indentation column))
399 | (setq column indentation))))
400 | (forward-line)))
401 | ;; ----------
402 | (save-excursion
403 | (goto-char start)
404 | (let ((buf (get-buffer-create " highlight-doxygen"))
405 | (src-buf (current-buffer)))
406 | ;; ----------
407 | ;; Copy code block to temp buffer, ignoring anything to the left
408 | ;; of the starting column of the code block.
409 | (with-current-buffer buf
410 | (delete-region (point-min) (point-max))
411 | ;; Ensure temp buffers doesn't keep major mode over calls.
412 | (fundamental-mode))
413 | (while (< (point) end)
414 | ;; Go to column, include a tab if it spans the intended column.
415 | (move-to-column column)
416 | (when (> (current-column) column)
417 | (backward-char))
418 | (let ((line (buffer-substring-no-properties
419 | (point)
420 | (min end (line-end-position))))
421 | (origin (point)))
422 | (with-current-buffer buf
423 | (insert line)
424 | (set-text-properties
425 | (line-beginning-position)
426 | (line-end-position)
427 | (list 'highlight-doxygen origin))
428 | (insert "\n")))
429 | (forward-line))
430 | ;; ----------
431 | ;; Highlight the code block.
432 | (save-excursion
433 | (goto-char start)
434 | (while (< (point) end)
435 | (move-to-column column)
436 | (when (> (current-column) column)
437 | (backward-char))
438 | (unless (eolp)
439 | (font-lock-prepend-text-property
440 | (point)
441 | (min end (line-beginning-position 2))
442 | 'face
443 | 'highlight-doxygen-code-block))
444 | (forward-line)))
445 | ;; ----------
446 | ;; Copy syntax highlighting from temp to original buffer.
447 | (with-current-buffer buf
448 | (when (ignore-errors
449 | (cond ((stringp mode)
450 | (let ((buffer-file-name
451 | (concat default-directory
452 | "dummy" mode)))
453 | (set-auto-mode))
454 | t)
455 | ((functionp mode)
456 | (funcall mode)
457 | t)
458 | ;; Don't highlight.
459 | (t nil)))
460 | (unless (eq major-mode 'fundamental-mode)
461 | (ignore-errors
462 | (font-lock-fontify-region (point-min) (point-max))))
463 | (goto-char (point-min))
464 | (while (not (eobp))
465 | (let ((origin (get-text-property (point) 'highlight-doxygen))
466 | next)
467 | (while (and (not (eolp))
468 | (setq next (next-single-property-change
469 | (point) 'face
470 | nil (line-end-position))))
471 | (let ((face (get-text-property (point) 'face)))
472 | (when face
473 | ;; Without this, code block containing comments
474 | ;; will look half done when rendered in a code
475 | ;; block.
476 | (dolist (old '(font-lock-comment-face
477 | font-lock-comment-delimiter-face
478 | font-lock-doc-face
479 | highlight-doxygen-comment
480 | default))
481 | (setq face (highlight-doxygen-replace-in-sexp
482 | 'highlight-doxygen-code-block
483 | old
484 | face)))
485 | (font-lock-prepend-text-property
486 | (+ origin (- (point) (line-beginning-position)))
487 | (+ origin (- next (line-beginning-position)))
488 | 'face
489 | face
490 | src-buf)))
491 | (goto-char next)))
492 | (forward-line))))))))
493 |
494 |
495 | (defun highlight-doxygen-forward-to-indentation ()
496 | "Move point to first text after comment starter in current line.
497 |
498 | Return non-nil if the line is not empty, it only contains
499 | whitespace and comment start characters."
500 | (skip-syntax-forward " ")
501 | (cond ((looking-at "\\(/\\*\\(!\\|\\*[^*]\\)\\|//\\(!\\|/[^/]\\)\\)")
502 | (goto-char (+ (match-beginning 0) 3)))
503 | ((eq (following-char) ?*)
504 | (forward-char)))
505 | (skip-syntax-forward " ")
506 | (not (eolp)))
507 |
508 |
509 | (defun highlight-doxygen-current-indentation ()
510 | "The current indentation, or nil if line is empty.
511 |
512 | \"Empty\", in this context mean that it only contains whitespace
513 | and comment start characters."
514 | (save-excursion
515 | (and (highlight-doxygen-forward-to-indentation)
516 | (current-column))))
517 |
518 |
519 | (defun highlight-doxygen-forward-to-paragraph-start (limit)
520 | "Move forward to start of Doxygen comment paragraph.
521 |
522 | Empty lines and highlighted code blocks are skipped.
523 |
524 | Return indentation for first line in paragraph, or nil if LIMIT is reached."
525 | (let ((res nil))
526 | (while
527 | (if (>= (point) limit)
528 | nil
529 | (setq res (highlight-doxygen-current-indentation))
530 | (not res))
531 | (forward-line))
532 | res))
533 |
534 |
535 | (defun highlight-doxygen-end-of-paragraph-position (limit)
536 | "Return the position of the end of the current paragraph, or nil.
537 |
538 | LIMIT is the end of the Doxygen comment."
539 | (save-excursion
540 | ;; Skip empty lines.
541 | (while (and (< (point) limit)
542 | (not (highlight-doxygen-current-indentation)))
543 | (forward-line))
544 | (let ((res nil))
545 | (while (and (< (point) limit)
546 | (highlight-doxygen-current-indentation))
547 | (setq res (line-end-position))
548 | (forward-line))
549 | res)))
550 |
551 |
552 | ;; Doxygen treats a block as a code block when it's indented four
553 | ;; steps more than the preceding paragraph.
554 | ;;
555 | ;; Note that text lines that step up the indentation doesn't qualify.
556 | ;;
557 | ;; Point is at the beginning of a Doxygen comment or after another
558 | ;; code block.
559 | (defun highlight-doxygen-find-and-highlight-markdown-code-block (limit)
560 | "Skip to next paragraph and maybe highlight a MarkDown code block.
561 |
562 | Move point to end of the current paragraph. If the paragraph is
563 | followed by a MarkDown code block (i.e. a block indented four
564 | spaces more than the paragraph), highlight the code block and
565 | move point to the paragraph after it.
566 |
567 | Do not search past LIMIT.
568 |
569 | Return non-nil if a paragraph was found.
570 |
571 | This function is intended to be used in a font-lock keyword."
572 | (let ((paragraph-indentation
573 | (highlight-doxygen-forward-to-paragraph-start limit)))
574 | (when paragraph-indentation
575 | ;; Skip to end of paragraph.
576 | (forward-line)
577 | (while (and (< (point) limit)
578 | (or
579 | (get-text-property (point) 'highlight-doxygen-ignore)
580 | (let ((indentation
581 | (highlight-doxygen-current-indentation)))
582 | (if indentation
583 | (progn
584 | ;; Record the last line of the paragraph.
585 | (setq paragraph-indentation indentation)
586 | t)
587 | nil))))
588 | (forward-line))
589 | ;; Skip to next non-empty line.
590 | (while (and (< (point) limit)
591 | (not (highlight-doxygen-current-indentation)))
592 | (forward-line))
593 | ;; Skip code block (if present).
594 | (let ((start (point))
595 | (least-indentation nil))
596 | (while (and
597 | (< (point) limit)
598 | ;; Stop at explicit code blocks (it will be skipped by
599 | ;; `highlight-doxygen-forward-to-paragraph-start' the
600 | ;; next time this function is called).
601 | (not (get-text-property (point) 'highlight-doxygen-ignore))
602 | (let ((indentation (highlight-doxygen-current-indentation)))
603 | (if indentation
604 | (if (< indentation (+ paragraph-indentation 4))
605 | ;; Indentation no longer least four spaces, stop.
606 | nil
607 | ;; Continue skipping.
608 | (setq least-indentation
609 | (if least-indentation
610 | (min least-indentation
611 | indentation)
612 | indentation))
613 | t)
614 | ;; Empty line in block.
615 | t)))
616 | (forward-line))
617 | (if least-indentation
618 | (highlight-doxygen-code-block
619 | (+ start least-indentation)
620 | (point))
621 | (goto-char start))))
622 | ;; By returning a non-nil value (regardless if a code block is
623 | ;; present), this function is called again when used in a
624 | ;; font-lock rule.
625 | paragraph-indentation))
626 |
627 |
628 | (defcustom highlight-doxygen-code-block-commands
629 | '(("code" "endcode")
630 | ("dot" "enddot")
631 | ("msc" "endmsc")
632 | ("startuml" "enduml")
633 | ("verbatim" "endverbatim"))
634 | "List of Doxygen commands that start a code block.
635 |
636 | Each entry in the list is a list on the form (START-COMMAND END-COMMAND)."
637 | :group 'highlight-doxygen
638 | :type 'sexp)
639 |
640 |
641 | (defcustom highlight-doxygen-block-major-mode-alist
642 | '(("code" . t)
643 | ("dot" . ".dot")
644 | ("msc" . ".msc")
645 | ("startuml" . ".plantuml")
646 | ("verbatim" . nil))
647 | "Alist used to determine major mode for Doxygen commands.
648 |
649 | The key (car part) is a Doxygen command. The value (cdr part)
650 | can be one of the following:
651 |
652 | - t -- the buffer is checked for the {.ext} construct
653 | - nil -- No special major mode is used.
654 | - A string -- An file extension
655 | - A symbol -- A major mode."
656 | :group 'highlight-doxygen
657 | :type 'sexp)
658 |
659 |
660 | (defun highlight-doxygen-block-major-mode (command)
661 | "Return the major mode or extension that should be used for block.
662 |
663 | When a major mode is returned, it is returned as a symbol. When
664 | it's an extension, it is returned as a string.
665 |
666 | Return nil when no suitable major mode is found.
667 |
668 | COMMAND is the Doxygen command of the block. The variable
669 | `highlight-doxygen-block-major-mode-alist' is used to determine
670 | the Emacs major mode should be used for highlighting.
671 |
672 | Point is initially placed after the command. If the Doxygen
673 | command supports the `{.ext}' construct, the point is moved to
674 | the end of the construct."
675 | (let ((entry (assoc command highlight-doxygen-block-major-mode-alist)))
676 | (and entry
677 | (let ((value (cdr entry)))
678 | (cond ((null value)
679 | nil)
680 | ((eq value t)
681 | (save-match-data
682 | (if (looking-at "{\\(\\.\\sw+\\)}")
683 | (progn
684 | (goto-char (match-end 0))
685 | (match-string 1))
686 | major-mode)))
687 | (t
688 | value))))))
689 |
690 |
691 | (defun highlight-doxygen-find-and-highlight-keywords-code-block (limit)
692 | "Highlight next code block within `code' or `verbatim' Doxygen commands.
693 |
694 | Do not search past LIMIT."
695 | (let ((start-regexp
696 | (concat
697 | "[\\@]\\("
698 | (regexp-opt (mapcar (lambda (e)
699 | (nth 0 e))
700 | highlight-doxygen-code-block-commands))
701 | "\\)")))
702 | (if (re-search-forward start-regexp limit t)
703 | (let ((mode (highlight-doxygen-block-major-mode (match-string 1)))
704 | (keyword-start (match-beginning 0)))
705 | (skip-syntax-forward " ")
706 | (when (and (eolp)
707 | (< (point) limit))
708 | (forward-line)
709 | (while (and (< (point) limit)
710 | (not (highlight-doxygen-forward-to-indentation)))
711 | (forward-line)))
712 | (let ((start (point))
713 | (end-regexp
714 | (concat
715 | "[\\@]"
716 | (regexp-opt (mapcar (lambda (e)
717 | (nth 1 e))
718 | highlight-doxygen-code-block-commands))
719 | "\\_>")))
720 | (if (re-search-forward end-regexp limit t)
721 | (save-excursion
722 | (let ((end (match-beginning 0))
723 | (keyword-end (match-beginning 0)))
724 | ;; Backup to last line containing anything
725 | (beginning-of-line)
726 | (highlight-doxygen-forward-to-indentation)
727 | (when (eq (point) end)
728 | (while
729 | (progn
730 | (forward-line -1)
731 | (setq end (line-beginning-position 2))
732 | (and
733 | (< start (point))
734 | (null
735 | (highlight-doxygen-forward-to-indentation))))))
736 | (highlight-doxygen-code-block start end mode)
737 | ;; Mark the code block (including code/endcode) to
738 | ;; ensure that the markdown code block highlighter
739 | ;; ignores it.
740 | (add-text-properties
741 | (save-excursion
742 | (goto-char keyword-start)
743 | (line-beginning-position))
744 | (save-excursion
745 | (goto-char keyword-end)
746 | (line-end-position))
747 | '(highlight-doxygen-ignore t))
748 | t))
749 | nil)))
750 | nil)))
751 |
752 |
753 | (defun highlight-doxygen-highlight-link-object ()
754 | "Highlight reference or filename following point, if any."
755 | (skip-syntax-forward "-")
756 | (let ((start (point))
757 | (end (point))
758 | (limit (line-end-position)))
759 | ;; Match file names and references.
760 | ;;
761 | ;; Example:
762 | ;;
763 | ;; myname.h
764 | ;; myfunc()
765 | ;; myfunc(unsigned long) <- Note the space
766 | (while (and (not (looking-at "\\s-"))
767 | (condition-case nil
768 | (progn
769 | (forward-sexp)
770 | (if (<= (point) limit)
771 | (progn
772 | (setq end (point))
773 | t)
774 | nil))
775 | (error nil))))
776 | (when (< start end)
777 | ;; TODO: How do we tell file names apart from references?
778 | (if (string-match "\\." (buffer-substring start end))
779 | ;; File name
780 | (font-lock-prepend-text-property
781 | start end 'face 'font-lock-constant-face)
782 | ;; Reference
783 | (highlight-doxygen-code-block start end major-mode)))))
784 |
785 | ;; -------------------------------------------------------------------
786 | ;; Font lock keywords
787 | ;;
788 |
789 | ;; --------------------
790 | ;; bold
791 | ;;
792 |
793 | (defcustom highlight-doxygen-bold-commands
794 | '("b")
795 | "List of Doxygen commands that make their argument bold."
796 | :group 'highlight-doxygen
797 | :type '(repeat string))
798 |
799 | ;; Note: `:inherit bold' is used over `:weight bold', to minimize the
800 | ;; number of faces a user or a theme would have to customize.
801 | (defface highlight-doxygen-bold
802 | '((t :inherit bold))
803 | "The face used to make text bold."
804 | :group 'highlight-doxygen)
805 |
806 |
807 | ;; --------------------
808 | ;; code
809 | ;;
810 |
811 | (defcustom highlight-doxygen-code-commands
812 | '("c" "retval")
813 | "List of Doxygen commands that make their argument code."
814 | :group 'highlight-doxygen
815 | :type '(repeat string))
816 |
817 | (defface highlight-doxygen-code
818 | '((t :inherit font-lock-constant-face))
819 | "The face used to highlight things as code within Doxygen comments.
820 |
821 | This is not used for code blocks."
822 | :group 'highlight-doxygen)
823 |
824 |
825 | ;; --------------------
826 | ;; emphasize
827 | ;;
828 |
829 | (defcustom highlight-doxygen-emphasize-commands
830 | '("e" "em")
831 | "List of Doxygen commands that emphasize their argument."
832 | :group 'highlight-doxygen
833 | :type '(repeat string))
834 |
835 | ;; Note: `:inherit italic' is used over `:slant italic', to minimize
836 | ;; the number of faces a user or a theme would have to customize.
837 | (defface highlight-doxygen-emphasize
838 | '((t :inherit italic))
839 | "The face used to make text emphasized."
840 | :group 'highlight-doxygen)
841 |
842 |
843 | ;; --------------------
844 | ;; exception
845 | ;;
846 |
847 | (defcustom highlight-doxygen-exception-commands
848 | '("exception" "idlexcept" "throw" "throws")
849 | "List of Doxygen commands that take an exception argument."
850 | :group 'highlight-doxygen
851 | :type '(repeat string))
852 |
853 | ;; Note: This mimics C++ mode.
854 | (defface highlight-doxygen-exception
855 | '((t :inherit font-lock-type-face))
856 | "The face for exceptions in Doxygen comments."
857 | :group 'highlight-doxygen)
858 |
859 |
860 | ;; --------------------
861 | ;; namespace
862 | ;;
863 |
864 | (defcustom highlight-doxygen-namespace-commands
865 | '("namespace")
866 | "List of Doxygen commands that take a namespace argument."
867 | :group 'highlight-doxygen
868 | :type '(repeat string))
869 |
870 | ;; Note: This mimics C++ mode.
871 | (defface highlight-doxygen-namespace
872 | '((t :inherit font-lock-constant-face))
873 | "The face for namespaces in Doxygen comments."
874 | :group 'highlight-doxygen)
875 |
876 |
877 | ;; --------------------
878 | ;; Class
879 | ;;
880 |
881 | (defcustom highlight-doxygen-qualified-type-commands
882 | '("class" "enum" "extends" "implements" "interface" "memberof"
883 | "protocol" "relates" "related" "relatesalso" "relatedalso"
884 | "struct" "union")
885 | "List of Doxygen commands that take a \"class\" argument."
886 | :group 'highlight-doxygen
887 | :type '(repeat string))
888 |
889 | (defface highlight-doxygen-type
890 | '((t :inherit font-lock-type-face))
891 | "The face used to highlight class arguments."
892 | :group 'highlight-doxygen)
893 |
894 |
895 | ;; --------------------
896 | ;; Group
897 | ;;
898 |
899 | ;; TODO: The `ingroup' commands can take multiple groups as
900 | ;; arguments. Since this is rule itself is included in a anchored
901 | ;; match, it's not possible to handle this using anchored matches, so
902 | ;; it must be done in elisp.
903 | (defcustom highlight-doxygen-group-commands
904 | '("addtogroup" "defgroup" "ingroup" "weakgroup")
905 | "List of Doxygen commands that take a \"group\" argument."
906 | :group 'highlight-doxygen
907 | :type '(repeat string))
908 |
909 | (defface highlight-doxygen-group
910 | '((t :inherit highlight))
911 | "The face used to highlight group arguments."
912 | :group 'highlight-doxygen)
913 |
914 |
915 | ;; --------------------
916 | ;; File names
917 | ;;
918 |
919 | (defface highlight-doxygen-filename
920 | '((t :inherit highlight))
921 | "The face used to highlight filename arguments."
922 | :group 'highlight-doxygen)
923 |
924 |
925 | (defcustom highlight-doxygen-filename-commands
926 | '("dir" "dontinclude" "example" "file" "htmlinclude" "include"
927 | "includedoc" "includelineno" "latexinclude" "verbinclude"
928 | ;; Note: also takes "( block_id )"
929 | "snippet" "snippetdoc" "snippetlineno"
930 | ;; Note: Also takes "["caption"] [=]"
931 | "diafile" "dotfile" "mscfile"
932 | ;; Note: Also takes "[]":
933 | "headerfile")
934 | "List of Doxygen commands that take a filename argument."
935 | :group 'highlight-doxygen
936 | :type '(repeat string))
937 |
938 |
939 | ;; --------------------
940 | ;; Reference (named page or anchor)
941 | ;;
942 |
943 | (defcustom highlight-doxygen-reference-commands
944 | '("ref" "refitem" "xrefitem")
945 | "List of Doxygen commands that take a reference argument."
946 | :group 'highlight-doxygen
947 | :type '(repeat string))
948 |
949 |
950 | ;; --------------------
951 | ;; Section label
952 | ;;
953 |
954 | (defcustom highlight-doxygen-section-label-commands
955 | '("cond" "if" "ifnot" "elseif")
956 | "List of Doxygen commands that take a \"section-label\" argument."
957 | :group 'highlight-doxygen
958 | :type '(repeat string))
959 |
960 | (defface highlight-doxygen-section-label
961 | '((t :inherit font-lock-type-face))
962 | "The face used to highlight section label arguments."
963 | :group 'highlight-doxygen)
964 |
965 |
966 | ;; --------------------
967 | ;; Variables
968 | ;;
969 |
970 | (defcustom highlight-doxygen-variable-commands
971 | '("a" "p" "tparam")
972 | "List of Doxygen commands that take a variable argument."
973 | :group 'highlight-doxygen
974 | :type '(repeat string))
975 |
976 | (defcustom highlight-doxygen-variable-with-dir-commands
977 | '("param")
978 | "List of Doxygen commands that take an optional dir and a variable argument."
979 | :group 'highlight-doxygen
980 | :type '(repeat string))
981 |
982 | (defface highlight-doxygen-direction
983 | '((t :inherit font-lock-builtin-face))
984 | "The face used to highlight parameter direction."
985 | :group 'highlight-doxygen)
986 |
987 | (defface highlight-doxygen-variable
988 | '((t :inherit font-lock-variable-name-face))
989 | "The face used to highlight variables in Doxygen comments."
990 | :group 'highlight-doxygen)
991 |
992 |
993 | ;; --------------------
994 | ;; Line of code
995 | ;;
996 |
997 | (defcustom highlight-doxygen-code-line-commands
998 | '("fn" "var" "typedef" "property" "overload")
999 | "List of Doxygen commands that take a line of code as argument."
1000 | :group 'highlight-doxygen
1001 | :type '(repeat string))
1002 |
1003 |
1004 | ;; --------------------
1005 | ;; Link object (member, type, page, filename, etc.)
1006 | ;;
1007 |
1008 | (defcustom highlight-doxygen-link-object-commands
1009 | '("copybrief" "copydetails" "copydoc")
1010 | "List of Doxygen commands that take a line of code or file name as argument."
1011 | :group 'highlight-doxygen
1012 | :type '(repeat string))
1013 |
1014 |
1015 | ;; --------------------
1016 | ;; Links
1017 | ;;
1018 |
1019 | (defface highlight-doxygen-link
1020 | '((t :inherit link))
1021 | "The face used to highlight links (URL:s) in Doxygen comments."
1022 | :group 'highlight-doxygen)
1023 |
1024 |
1025 | ;; --------------------
1026 | ;; Titles
1027 | ;;
1028 |
1029 | ;; mainpage -- heading-1
1030 | ;; section -- heading-2
1031 | ;; subsection -- heading-3
1032 | ;; subsubsection -- heading-4
1033 | ;; paragraph -- heading-5
1034 |
1035 | ;; page -- heading-2
1036 | ;; subpage -- heading-3
1037 |
1038 | (defface highlight-doxygen-label
1039 | '((t :inherit font-lock-type-face))
1040 | "The face used to highlight level 1 headings."
1041 | :group 'highlight-doxygen)
1042 |
1043 | (defface highlight-doxygen-heading-1
1044 | '((t :inherit outline-1))
1045 | "The face used to highlight level 1 headings."
1046 | :group 'highlight-doxygen)
1047 |
1048 |
1049 | (defface highlight-doxygen-heading-2
1050 | '((t :inherit outline-2))
1051 | "The face used to highlight level 2 headings."
1052 | :group 'highlight-doxygen)
1053 |
1054 |
1055 | (defface highlight-doxygen-heading-3
1056 | '((t :inherit outline-3))
1057 | "The face used to highlight level 3 headings."
1058 | :group 'highlight-doxygen)
1059 |
1060 |
1061 | (defface highlight-doxygen-heading-4
1062 | '((t :inherit outline-4))
1063 | "The face used to highlight level 4 headings."
1064 | :group 'highlight-doxygen)
1065 |
1066 |
1067 | (defface highlight-doxygen-heading-5
1068 | '((t :inherit outline-5))
1069 | "The face used to highlight level 5 headings."
1070 | :group 'highlight-doxygen)
1071 |
1072 |
1073 | (defcustom highlight-doxygen-title-commands-alist
1074 | '((("mainpage") . highlight-doxygen-heading-1)
1075 | ;; Note: Doxygen use the same font size for "par" as
1076 | ;; subsubsections.
1077 | (("par" "vhdlflow") . highlight-doxygen-heading-4))
1078 | "Alist from list of Doxygen commands to faces.
1079 |
1080 | The Doxygen commands should take one argument, a title."
1081 | :group 'highlight-doxygen
1082 | :type 'sexp)
1083 |
1084 |
1085 | ;; Note: According to Doxygen, "subpage" requires that the title is
1086 | ;; placed within quotes whereas the title of the other commands should
1087 | ;; not use quotes. The highlighting rules generated from this
1088 | ;; highlight the rest of the line as a title, regardless of quoting
1089 | ;; style.
1090 | (defcustom highlight-doxygen-name-title-commands-alist
1091 | '((("section" "page") . highlight-doxygen-heading-2)
1092 | (("subsection" "subpage") . highlight-doxygen-heading-3)
1093 | (("subsubsection") . highlight-doxygen-heading-4)
1094 | (("paragraph") . highlight-doxygen-heading-5))
1095 | "Alist from list of Doxygen commands to faces.
1096 |
1097 | The Doxygen commands should take two arguments, a name and a
1098 | title."
1099 | :group 'highlight-doxygen
1100 | :type 'sexp)
1101 |
1102 |
1103 | ;; --------------------
1104 | ;; The font-lock rules
1105 | ;;
1106 |
1107 |
1108 | (defvar highlight-doxygen-comment-start-position nil)
1109 | (make-variable-buffer-local 'highlight-doxygen-comment-start-position)
1110 |
1111 | (defvar highlight-doxygen-comment-end-position nil)
1112 | (make-variable-buffer-local 'highlight-doxygen-comment-end-position)
1113 |
1114 | (defvar highlight-doxygen-start-column nil)
1115 | (make-variable-buffer-local 'highlight-doxygen-start-column)
1116 |
1117 |
1118 | ;; Note: In case a face has a corresponding variable (like
1119 | ;; `font-lock-constant-face', the face expression doesn't quote the
1120 | ;; name of the face. Technically, the face expression refers to the
1121 | ;; variable. This allows users to customize the face be changing the
1122 | ;; variable. However, this technique is deprecated in favour of using
1123 | ;; `face-remapping-alist'.
1124 |
1125 | (defun highlight-doxygen-anchored-keywords-template ()
1126 | "List of font-lock keywords that will be converted to anchored submatches.
1127 |
1128 | The MATCHER will be wrapped in a call to
1129 | `highlight-doxygen-forward-search' and pre and post match forms
1130 | will be added.
1131 |
1132 | Note that these rules can't contain anchored rules themselves."
1133 | (let ((title-rules '()))
1134 | (dolist (pair highlight-doxygen-title-commands-alist)
1135 | (let ((commands (car pair))
1136 | (face (cdr pair)))
1137 | (push `(,(concat "[\\@]\\_<"
1138 | (regexp-opt commands)
1139 | "\\s-+"
1140 | "\\(.*\\)")
1141 | (1 (quote ,face) prepend))
1142 | title-rules)))
1143 | (dolist (pair highlight-doxygen-name-title-commands-alist)
1144 | (let ((commands (car pair))
1145 | (face (cdr pair)))
1146 | (push `(,(concat "[\\@]\\_<"
1147 | (regexp-opt commands)
1148 | "\\s-+"
1149 | "\\_<\\(\\sw+\\)"
1150 | "\\(\\s-+"
1151 | "\\(.*\\)\\)?")
1152 | (1 'highlight-doxygen-label prepend)
1153 | (2 (quote ,face) prepend t))
1154 | title-rules)))
1155 | (append
1156 | `(
1157 | ;; --------------------
1158 | ;; Highlight every line in the Doxygen block.
1159 | ;;
1160 | ;; Unlike plain comment highlighting, make the highlighting
1161 | ;; follow the indentation of the Doxygen comment.
1162 | (highlight-doxygen-match-comment-line
1163 | (0 'highlight-doxygen-comment prepend))
1164 | ;; --------------------
1165 | ;; Explicit code blocks
1166 | (highlight-doxygen-find-and-highlight-keywords-code-block)
1167 | ;; --------------------
1168 | ;; Implicit (indented) code blocks
1169 | (highlight-doxygen-find-and-highlight-markdown-code-block)
1170 | ;; --------------------
1171 | ;; Doxygen command.
1172 | (,(concat "[\\@]"
1173 | "\\_<\\([a-z]+\\)\\_>")
1174 | (1 'highlight-doxygen-command prepend))
1175 |
1176 | ;; ----------------------------------------
1177 | ;; Inline constructs.
1178 |
1179 | ;; --------------------
1180 | ;; Type name
1181 |
1182 | (highlight-doxygen-match-camel-case
1183 | (1 font-lock-type-face prepend))
1184 |
1185 | ;; --------------------
1186 | ;; Qualified class name
1187 |
1188 | ("\\_<\\(\\sw+\\)\\(::\\|#\\)"
1189 | (1 font-lock-type-face prepend))
1190 |
1191 | ;; --------------------
1192 | ;; Function name
1193 | ("\\_<\\(\\(\\sw\\)+\\)()"
1194 | (1 font-lock-function-name-face prepend))
1195 |
1196 | ;; --------------------
1197 | ;; Links (URI:s). See RFC 3986, chapter 3.
1198 |
1199 | ("\\_<\\([a-zA-Z][-a-zA-Z0-9+.]*://[^ \t\n]*\\)"
1200 | (1 'highlight-doxygen-link prepend)))
1201 | title-rules
1202 | `(
1203 | ;; ------------------------------
1204 | ;; Various command signatures.
1205 | ;;
1206 |
1207 | ;; --------------------
1208 | ;; bold
1209 | (,(concat "[\\@]\\_<"
1210 | (regexp-opt highlight-doxygen-bold-commands)
1211 | "\\s-+"
1212 | "\\_<\\(\\sw+\\)")
1213 | (1 'highlight-doxygen-bold prepend))
1214 |
1215 | ;; --------------------
1216 | ;; code
1217 | (,(concat "[\\@]\\_<"
1218 | (regexp-opt highlight-doxygen-code-commands)
1219 | "\\s-+"
1220 | "\\_<\\(\\sw+\\)")
1221 | (1 'highlight-doxygen-code prepend))
1222 |
1223 | ;; --------------------
1224 | ;; emphasize
1225 | (,(concat "[\\@]\\_<"
1226 | (regexp-opt highlight-doxygen-emphasize-commands)
1227 | "\\s-+"
1228 | "\\_<\\(\\sw+\\)")
1229 | (1 'highlight-doxygen-emphasize prepend))
1230 |
1231 | ;; --------------------
1232 | ;; Type name
1233 |
1234 | (,(concat "[\\@]\\_<"
1235 | (regexp-opt highlight-doxygen-qualified-type-commands)
1236 | "\\s-+"
1237 | ;; Skip qualifiers.
1238 | "\\_<\\(?:\\sw+\\(?:::\\|#\\)\\)*"
1239 | "\\_<\\(\\sw+\\)")
1240 | (1 'highlight-doxygen-type prepend))
1241 |
1242 | ;; --------------------
1243 | ;; exception
1244 |
1245 | (,(concat "[\\@]\\_<"
1246 | (regexp-opt highlight-doxygen-exception-commands)
1247 | "\\s-+"
1248 | ;; Skip qualifiers.
1249 | "\\_<\\(?:\\sw+\\(?:::\\|#\\)\\)*"
1250 | "\\(\\sw+\\)")
1251 | (1 'highlight-doxygen-exception prepend))
1252 |
1253 | ;; --------------------
1254 | ;; namespace
1255 |
1256 | (,(concat "[\\@]\\_<"
1257 | (regexp-opt highlight-doxygen-namespace-commands)
1258 | "\\s-+"
1259 | ;; Skip qualifiers.
1260 | "\\_<\\(?:\\sw+\\(?:::\\|#\\)\\)*"
1261 | "\\_<\\(\\sw+\\)")
1262 | (1 'highlight-doxygen-namespace prepend))
1263 |
1264 | ;; --------------------
1265 | ;; Group name
1266 | (,(concat "[\\@]\\_<"
1267 | (regexp-opt highlight-doxygen-group-commands)
1268 | "\\s-+"
1269 | "\\_<\\(\\sw+\\)")
1270 | (1 'highlight-doxygen-group prepend))
1271 |
1272 | ;; --------------------
1273 | ;; File name
1274 | (,(concat "[\\@]\\_<"
1275 | (regexp-opt highlight-doxygen-filename-commands)
1276 | "\\s-+"
1277 | "\\_<\\([a-zA-Z0-9_:/\\.]+\\)")
1278 | (1 'highlight-doxygen-filename prepend))
1279 |
1280 | ;; --------------------
1281 | ;; Reference
1282 |
1283 | ;; Note: The Doxygen documentation doesn't specify the format
1284 | ;; of a reference, this code use a combination of word
1285 | ;; characters, symbol characters, and punctuation
1286 | ;; characters. Another approach would be to match every
1287 | ;; character except whitespace. Unfortunately, "\\S-" might
1288 | ;; match newlines, so the search must be restricted to the end
1289 | ;; of the line that contains the Doxygen command.
1290 | (,(concat "[\\@]\\_<"
1291 | (regexp-opt highlight-doxygen-reference-commands)
1292 | "\\s-+"
1293 | "\\(\\(\\sw\\|\\s_\\|\\s.\\)+\\)")
1294 | (1 'highlight-doxygen-link prepend))
1295 |
1296 | ;; --------------------
1297 | ;; section-label (`if' and `elseif' etc.)
1298 |
1299 | ;; TODO: The section label can be a complex expression like
1300 | ;; "(TEST1 && !TEST2). Since this is rule itself is included in a
1301 | ;; anchored match, it's not possible to handle this using anchored
1302 | ;; matches, so it must be done in elisp.
1303 | (,(concat "[\\@]\\_<"
1304 | (regexp-opt highlight-doxygen-section-label-commands)
1305 | "\\s-+"
1306 | "\\_<\\(\\sw+\\)")
1307 | (1 'highlight-doxygen-section-label prepend))
1308 |
1309 | ;; --------------------
1310 | ;; Variable
1311 |
1312 | (,(concat "[\\@]\\_<"
1313 | (regexp-opt highlight-doxygen-variable-commands)
1314 | "\\s-+"
1315 | "\\_<\\(\\sw+\\)")
1316 | (1 'highlight-doxygen-variable prepend))
1317 |
1318 | ;; --------------------
1319 | ;; Variable with direction
1320 |
1321 | (,(concat "[\\@]\\_<"
1322 | (regexp-opt highlight-doxygen-variable-with-dir-commands)
1323 | "\\_>"
1324 | "\\s-*"
1325 | "\\(?:\\["
1326 | "\\(?:\\(in\\)\\|\\(out\\)\\|\\(in\\),\\(out\\)\\)"
1327 | "\\]\\)?"
1328 | "\\s-*"
1329 | "\\(\\_<\\sw+\\)?")
1330 | (1 'highlight-doxygen-direction prepend t) ; in
1331 | (2 'highlight-doxygen-direction prepend t) ; out
1332 | (3 'highlight-doxygen-direction prepend t) ; in (part of in,out)
1333 | (4 'highlight-doxygen-direction prepend t) ; out (part of in,out)
1334 | (5 'highlight-doxygen-variable prepend t))
1335 |
1336 | ;; --------------------
1337 | ;; Line of code
1338 |
1339 | (,(concat "[\\@]\\_<"
1340 | (regexp-opt highlight-doxygen-code-line-commands)
1341 | "\\s-+\\(.*\\)$")
1342 | (0 (progn
1343 | (highlight-doxygen-code-block
1344 | (match-beginning 1)
1345 | (match-end 1)
1346 | major-mode)
1347 | nil)))
1348 |
1349 | ;; --------------------
1350 | ;; Reference or file name
1351 |
1352 | (,(concat "[\\@]\\_<"
1353 | (regexp-opt highlight-doxygen-link-object-commands)
1354 | "\\_>")
1355 | (0 (progn
1356 | ;; This will apply suitable highlighting to whatever is
1357 | ;; after the command.
1358 | (highlight-doxygen-highlight-link-object)
1359 | nil)))
1360 |
1361 | ;; --------------------
1362 | ;; Highlight "`foo`". Note that in Doxygen a quote cancels a
1363 | ;; backquote.
1364 | ;;
1365 | ;; TODO: Multi-line support.
1366 | ("`\\([^\n`']+\\)`"
1367 | (1 (progn
1368 | (goto-char (match-end 0))
1369 | font-lock-constant-face)
1370 | prepend))))))
1371 |
1372 |
1373 | (defun highlight-doxygen-forward-search (matcher limit)
1374 | "Search for MATCHER but skip Doxygen code blocks.
1375 |
1376 | If MATCHER is a string `re-search-forward' is used, otherwise it
1377 | is called as a function.
1378 |
1379 | Do not search past LIMIT."
1380 | (let (res)
1381 | (while (and
1382 | (setq res (let ((old-point (point)))
1383 | (and
1384 | (< (point) limit)
1385 | (if (stringp matcher)
1386 | (re-search-forward matcher limit t)
1387 | (funcall matcher limit))
1388 | ;; If the matcher function succeeds but
1389 | ;; doesn't move the point, Emacs hangs.
1390 | (< old-point (point)))))
1391 | (get-text-property (point) 'highlight-doxygen-code)))
1392 | res))
1393 |
1394 |
1395 | (defun highlight-doxygen--pre-match-form ()
1396 | "Prepare for submatches in an anchored font-lock rule.
1397 |
1398 | Move point to start of current Doxygen comment and return the
1399 | end, making it the region the sub matcher will be applied to."
1400 | ;; Font-lock moves point one position in an attempt to avoid
1401 | ;; infinite searches after matching the main matcher. We need
1402 | ;; to move the point back to the start of the comment to make
1403 | ;; the block highlighting work properly.
1404 | (goto-char highlight-doxygen-comment-start-position)
1405 | ;; Search limit
1406 | highlight-doxygen-comment-end-position)
1407 |
1408 |
1409 | (defun highlight-doxygen--post-match-form ()
1410 | "Wind up an anchored font-lock rule."
1411 | ;; TODO: If this is nil, font-lock work but font-lock-studio
1412 | ;; hangs. Find out why!
1413 | (goto-char highlight-doxygen-comment-end-position))
1414 |
1415 |
1416 | (defun highlight-doxygen-compose-font-lock-keywords ()
1417 | "Construct the font-lock keywords for highlighting Doxygen comments."
1418 | (let (subrules '())
1419 | (dolist (template (highlight-doxygen-anchored-keywords-template))
1420 | (let ((expr (nth 0 template)))
1421 | (unless (stringp expr)
1422 | (setq expr (list 'function expr))) ; Same as #'
1423 | (push `((lambda (limit)
1424 | (highlight-doxygen-forward-search ,expr limit))
1425 | (highlight-doxygen--pre-match-form)
1426 | (highlight-doxygen--post-match-form)
1427 | ,@(cdr template))
1428 | subrules)))
1429 | `((highlight-doxygen-match-comment ,@(nreverse subrules)))))
1430 |
1431 |
1432 |
1433 | ;; -------------------------------------------------------------------
1434 | ;; Comment matcher.
1435 | ;;
1436 |
1437 | (defun highlight-doxygen-next-comment (limit)
1438 | "Search for next Doxygen comment.
1439 |
1440 | Stop search at LIMIT. If a Doxygen comment is found, move point
1441 | and return non-nil. Otherwise nil is returned (point may be
1442 | moved)."
1443 | (let (res)
1444 | (while
1445 | (and
1446 | (setq res (re-search-forward
1447 | highlight-doxygen-commend-start-regexp
1448 | limit t))
1449 | ;; Continue looping if:
1450 | (or (and
1451 | highlight-doxygen-ignore-triple-slash-comments
1452 | (save-excursion
1453 | (goto-char (match-beginning 0))
1454 | (looking-at highlight-doxygen-triple-slash-comment-regexp)))
1455 | (let ((state (syntax-ppss)))
1456 | (or
1457 | ;; Not in comment?
1458 | (not (nth 4 state))
1459 | ;; At the start of the comment?
1460 | (not (eq (match-beginning 0) (nth 8 state))))))))
1461 | (when res
1462 | (goto-char (match-beginning 0)))
1463 | res))
1464 |
1465 |
1466 | (defun highlight-doxygen-move-end-of-comment ()
1467 | "Move point to end of Doxygen comment.
1468 |
1469 | Treat consecutive Doxygen comments like one."
1470 | (let ((end (point)))
1471 | (while
1472 | (if (forward-comment 1)
1473 | (progn
1474 | (setq end (point))
1475 | (skip-chars-forward " \t\n")
1476 | (looking-at highlight-doxygen-commend-start-regexp))
1477 | ;; Guard against being enabled in modes where the comment
1478 | ;; syntax doesn't match
1479 | ;; `highlight-doxygen-commend-start-regexp'.
1480 | (setq end (line-end-position))
1481 | nil))
1482 | (goto-char end)
1483 | (when (and (eolp)
1484 | (not (bolp)))
1485 | (forward-line))))
1486 |
1487 |
1488 | (defun highlight-doxygen-match-comment (limit)
1489 | "Find next Doxygen comment.
1490 |
1491 | Do not search past LIMIT.
1492 |
1493 | Set `highlight-doxygen-comment-end-position' to end of Doxygen comment."
1494 | (let ((res (highlight-doxygen-next-comment limit)))
1495 | (when res
1496 | (setq highlight-doxygen-comment-start-position (point))
1497 | (setq highlight-doxygen-comment-end-position
1498 | ;; Respect `limit'.
1499 | ;;
1500 | ;; In normal operation, the refontified region is always
1501 | ;; extended to include the full comment. However, when
1502 | ;; using font-lock studio (a debugger for font-lock
1503 | ;; keywords) the user may use a smaller region.
1504 | (min
1505 | (save-excursion
1506 | (highlight-doxygen-move-end-of-comment)
1507 | (point))
1508 | limit))
1509 | (setq highlight-doxygen-start-column (current-column)))
1510 | res))
1511 |
1512 |
1513 | (defun highlight-doxygen-match-comment-line (limit)
1514 | "Match a single Doxygen comment line.
1515 |
1516 | Do not search past LIMIT."
1517 | (while (and (< (current-column) highlight-doxygen-start-column)
1518 | (not (eolp))
1519 | (memq (following-char) '(?\s ?\t)))
1520 | (forward-char))
1521 | (if (or (and (eolp)
1522 | (not (bolp)))
1523 | (> (point) limit))
1524 | nil
1525 | (set-match-data (list (point) (min (save-excursion
1526 | (forward-line)
1527 | (point))
1528 | limit)))
1529 | (forward-line)
1530 | t))
1531 |
1532 |
1533 | (defun highlight-doxygen-match-camel-case (limit)
1534 | "Search for next type, which is a CamelCase word.
1535 |
1536 | Do not search past LIMIT.
1537 |
1538 | Constructs like `CamelCase(' are ignored, as they are assumed to
1539 | be function calls.
1540 |
1541 | Constructs like `CamelCase.h' are ignores, as they look like file
1542 | names."
1543 | (let (res)
1544 | (while (and (setq res (re-search-forward
1545 | (concat "\\_<\\("
1546 | ;; Match a word written using
1547 | ;; CamelCase, starting with a
1548 | ;; capital letter.
1549 | ;;
1550 | ;; TODO: Allow "_"?
1551 | "[A-Z]+[a-zA-Z0-9]*[a-z]+[a-zA-Z0-9]*"
1552 | "[A-Z][a-zA-Z0-9]+"
1553 | "\\)\\_>")
1554 | limit t))
1555 | (or (save-excursion
1556 | ;; This is a function call, ignore.
1557 | (skip-chars-forward " \t")
1558 | (eq (following-char) ?\( ))
1559 | (save-match-data
1560 | ;; This is a file extension, ignore.
1561 | (looking-at "\\.[a-zA-Z]+\\_>")))))
1562 | res))
1563 |
1564 |
1565 | ;; -------------------------------------------------------------------
1566 | ;; Region extender.
1567 | ;;
1568 |
1569 | (defun highlight-doxygen-inside-special-comment ()
1570 | "Return start of Doxygen-style comment, or nil.
1571 |
1572 | Treat consecutive line comments like one block."
1573 | (save-excursion
1574 | (let ((res nil))
1575 | (while
1576 | (progn
1577 | (skip-chars-backward " \t")
1578 | (when (and (not (bobp))
1579 | (bolp))
1580 | (backward-char))
1581 | (let ((state (syntax-ppss)))
1582 | (if (nth 4 state) ; Comment
1583 | (progn
1584 | (goto-char (nth 8 state))
1585 | (if (looking-at highlight-doxygen-commend-start-regexp)
1586 | (progn
1587 | (setq res (point))
1588 | t)
1589 | nil))
1590 | nil))))
1591 | res)))
1592 |
1593 |
1594 | (defun highlight-doxygen-extend-region-full-comment ()
1595 | "Extend font-lock region to include the full Doxygen comment."
1596 | (save-excursion
1597 | (let ((res nil))
1598 | (goto-char font-lock-beg)
1599 | (let ((start (highlight-doxygen-inside-special-comment)))
1600 | (when (and start
1601 | (< start font-lock-beg))
1602 | (setq font-lock-beg start)
1603 | (setq res t)))
1604 | (goto-char font-lock-end)
1605 | (let ((start (highlight-doxygen-inside-special-comment)))
1606 | (when start
1607 | (highlight-doxygen-move-end-of-comment)
1608 | (when (< font-lock-end (point))
1609 | (setq font-lock-end (point))
1610 | (setq res t))))
1611 | res)))
1612 |
1613 |
1614 | ;; -------------------------------------------------------------------
1615 | ;; The modes.
1616 | ;;
1617 |
1618 |
1619 | (defvar highlight-doxygen--old-c-doc-rules nil)
1620 |
1621 | ;;;###autoload
1622 | (define-minor-mode highlight-doxygen-mode
1623 | "Minor mode that highlights Doxygen comments."
1624 | :group 'highlight-doxygen
1625 | ;; TODO: Cache the keywords.
1626 | (if highlight-doxygen-mode
1627 | (progn
1628 | (add-to-list 'font-lock-extend-region-functions
1629 | #'highlight-doxygen-extend-region-full-comment)
1630 | (add-to-list 'font-lock-extra-managed-props 'highlight-doxygen-code)
1631 | (add-to-list 'font-lock-extra-managed-props 'highlight-doxygen-ignore)
1632 | ;; Remove built-in c-doc rules, to avoid it interfering with
1633 | ;; our rules.
1634 | (when (fboundp 'c-compose-keywords-list)
1635 | (let ((c-doc-keywords (c-compose-keywords-list '())))
1636 | (set (make-local-variable 'highlight-doxygen--old-c-doc-rules)
1637 | c-doc-keywords)
1638 | (font-lock-remove-keywords nil c-doc-keywords)))
1639 | (font-lock-add-keywords nil
1640 | (highlight-doxygen-compose-font-lock-keywords))
1641 | (setq font-lock-multiline t))
1642 | ;; Note: `font-lock-multiline' is not restored. It may have gotten
1643 | ;; set by some other minor mode. Besides, it doesn't hurt keeping
1644 | ;; it set to t.
1645 | (setq font-lock-extend-region-functions
1646 | (delq 'highlight-doxygen-extend-region-full-comment
1647 | font-lock-extend-region-functions))
1648 | (setq font-lock-extra-managed-props
1649 | (delq 'highlight-doxygen-code font-lock-extra-managed-props))
1650 | (setq font-lock-extra-managed-props
1651 | (delq 'highlight-doxygen-ignore font-lock-extra-managed-props))
1652 | (font-lock-remove-keywords nil
1653 | (highlight-doxygen-compose-font-lock-keywords))
1654 | (font-lock-add-keywords nil highlight-doxygen--old-c-doc-rules))
1655 | ;; As of Emacs 25, `font-lock-fontify-buffer' is not legal to
1656 | ;; call, instead `font-lock-flush' should be used.
1657 | (if (fboundp 'font-lock-flush)
1658 | (font-lock-flush)
1659 | (when font-lock-mode
1660 | (with-no-warnings
1661 | (font-lock-fontify-buffer)))))
1662 |
1663 |
1664 |
1665 | ;;;###autoload
1666 | (define-global-minor-mode highlight-doxygen-global-mode highlight-doxygen-mode
1667 | (lambda ()
1668 | (when (apply #'derived-mode-p highlight-doxygen-modes)
1669 | (highlight-doxygen-mode 1)))
1670 | :group 'highlight-doxygen
1671 | :require 'highlight-doxygen)
1672 |
1673 |
1674 | (provide 'highlight-doxygen)
1675 |
1676 | ;;; highlight-doxygen.el ends here
1677 |
--------------------------------------------------------------------------------