├── .travis.yml ├── CHANGES.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── DOCUMENTATION.md ├── LICENSE ├── Makefile.in ├── NOTICE ├── README.md ├── SECURITY.md ├── codedoc-128.png ├── codedoc-160.png ├── codedoc-256.png ├── codedoc.1 ├── codedoc.c ├── codedoc.opacity ├── codedoc.xsd ├── config.guess ├── config.sub ├── configure ├── configure.ac ├── install-sh ├── mmd.c ├── mmd.h ├── snap └── snapcraft.yaml ├── testfiles ├── body.cxx ├── body.md ├── class.cxx ├── enum.cxx ├── function.cxx ├── functype.cxx ├── namespace.cxx ├── struct.cxx └── type.cxx ├── zipc.c └── zipc.h /.travis.yml: -------------------------------------------------------------------------------- 1 | # 2 | # Travis CI configuration file for codedoc. 3 | # 4 | 5 | language: c 6 | 7 | env: 8 | global: 9 | # The next declaration is the encrypted COVERITY_SCAN_TOKEN, created 10 | # via the "travis encrypt" command using the project repo's public key 11 | - secure: "BKEEg6eBwL9WaIglQOIv+IhOHuvFDI5xm4VefrNQjMoxZM5TaW/UHmLuOSLOdQH/mapMtJi7Gz6tULDt9BLfgq5SwqfTmMlryIs0nTfiOU0CDGWxGe1fUsZ58MIxdk9Y7AaRVeaLkt7Ns2Uwj9/x0IkS3xdJ4Loy9iTpOuQZTfBelm8FrbhWpXraUIK1sMwn5MhPDIAVktG5sVwME5kEwxU+6KhXazXlDGsAJKdvT1M2kiLJqCfYo2PWqCP4fv1D3EuIgsTDYXcOGfqy3rlLxBGWKJ7r/NaMpujELJwGLDbL6NdCI1ymsvmH1wSnj14sYTPncfYvNRu/pTtmQt0sUZtrQbrjvW5lYOaD5eDtBIWiNBU+b8WQBAMAiSpCu+EzGXmMCy3qJaxp+XFM8pPE4RzxY5W8UPfAJIvXPyfyDnMWp5yUK7dDHiMyXcpwEx8OeDYS16riOATrUObyMYYrWLC/0/PmJns0ZwQ9cl6JL6GwDWksjEGMu7uW1/TooziudXx9+xfW/p2FIxYk81PpFD5+iikLRGoTqhYsUWwyTZshdYpMyg8w6Vv3pf592MTAtVrpclOza9/IUDjweVik531zF433WjeQOnf/OGhZ3vBqhw5ECNC59ylgOof/STxvkBk74e5voO1XQG8tlmUYFbd2Vbyrqod20u7UwgPoR/0=" 12 | 13 | before_install: 14 | - echo -n | openssl s_client -connect https://scan.coverity.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee -a /etc/ssl/certs/ca- 15 | 16 | jobs: 17 | include: 18 | # Linux-specific build stuff 19 | - os: linux 20 | dist: focal 21 | virt: vm 22 | env: 23 | - ASAN_OPTIONS=leak_check_at_exit=false 24 | script: make sanitizer && make test && make cppcheck 25 | addons: 26 | apt: 27 | packages: [cppcheck, libmxml-dev] 28 | coverity_scan: 29 | project: 30 | name: "michaelrsweet/codedoc" 31 | description: "A Code Documentation Utility" 32 | notification_email: michael.r.sweet@gmail.com 33 | build_command_prepend: "make clean" 34 | build_command: "make" 35 | branch_pattern: coverity_scan 36 | 37 | # macOS-specific build stuff 38 | - os: osx 39 | osx_image: xcode12.2 40 | script: make sanitizer && make test 41 | addons: 42 | homebrew: 43 | packages: [libmxml] 44 | update: true 45 | 46 | notifications: 47 | email: 48 | recipients: 49 | - msweet@msweet.org 50 | -------------------------------------------------------------------------------- /CHANGES.md: -------------------------------------------------------------------------------- 1 | Changes in Codedoc 2 | ================== 3 | 4 | 5 | Changes in v3.8 (YYYY-MM-DD) 6 | ---------------------------- 7 | 8 | - Fixed bugs in the markdown parser. 9 | 10 | 11 | Changes in v3.7 (2024-03-24) 12 | ---------------------------- 13 | 14 | - Now require Mini-XML 4.x. 15 | - Now include a configure script. 16 | - Added quoting of "." and "'" at the beginning of lines and now use the ".IP" 17 | macro instead of ".IN" in man output (Issue #12) 18 | - Added support for `@body@` comment directive to add body text inline with code 19 | (Issue #10) 20 | - Added highlighting of HTML and XML in code-fenced markdown (Issue #19) 21 | - Added highlighting of CSS in code-fenced markdown. 22 | - Added highlighting of reserved words, numbers, and strings in reference 23 | documentation, to match markdown code example highlighting. 24 | - Fixed double-free bug (Issue #16) 25 | - Fixed some bugs detected with fuzzing (Issue #13, Issue #14, Issue #15) 26 | - Fixed support for markdown code fences and indentation in code example 27 | comments. 28 | - Cleaned up some issues reported by Coverity and Cppcheck. 29 | 30 | 31 | Changes in v3.6 (2020-12-31) 32 | ---------------------------- 33 | 34 | - Added support for syntax highlighting of C and C++ code. 35 | - Added support for literal links (functions, types, etc.) using the "@@" 36 | target. 37 | - Added support for `::WIDTHxHEIGHT` in image (ALT) text. 38 | - Added support for markdown-style block quotes in comments. 39 | - Fixed support for embedded images in EPUB output. 40 | - Fixed some parsing issues for the public typedef - private struct design 41 | pattern, resulting in undocumented typedefs. 42 | - Fixed a few Cppcheck and LGTM-detected bugs. 43 | - No longer output unnecessary whitespace in HTML/EPUB output, for a modest 44 | savings in file size. 45 | 46 | 47 | Changes in v3.5 (2020-10-09) 48 | ---------------------------- 49 | 50 | - Added support for C++ block comments. 51 | - Fixed support for function types. 52 | - Fixed support for private typedef struct/class/union constructions. 53 | - Fixed support for markdown bullet lists. 54 | - Fixed output of Unicode text. 55 | - Now use the "title" class for the cover image in HTML and EPUB output. 56 | - Now place the table of contents along the side for HTML output. 57 | - No longer strip quoted text ('text') in comments unless the text ends with 58 | '()'. 59 | 60 | 61 | Changes in v3.4 (2019-12-28) 62 | ---------------------------- 63 | 64 | - Added support for C++ namespaces (Issue #7) 65 | - Silenced some warnings from the LGTM security scanner. 66 | 67 | 68 | Changes in v3.3 (2019-11-17) 69 | ---------------------------- 70 | 71 | - Added basic markdown support in comments (Issue #6) 72 | - Added a `--language` option to override the default documentation language 73 | "en-US". 74 | - EPUB and HTML output now set the "generator" META content. 75 | - Did some minor code reorganization/cleanup. 76 | 77 | 78 | Changes in v3.2 (2019-08-28) 79 | ---------------------------- 80 | 81 | - The default HTML stylesheet no longer puts an outline box around monospaced 82 | text (Issue #2) 83 | - Fixed signed character issues with fuzzer-generated "code" (Issue #3, 84 | Issue #4) 85 | - Fixed a buffer overflow issue with fuzzer-generated "code" (Issue #5) 86 | - Now use the base name of the cover image filename in HTML output. 87 | - Fixed some markdown parsing issues. 88 | 89 | 90 | Changes in v3.1 (2019-02-19) 91 | ---------------------------- 92 | 93 | - Fixed compile problems with Mini-XML v3.0. 94 | - Greatly improved scanning of HTML content when generating the table of 95 | contents. 96 | - Updated the markdown support with external links, additional inline markup, 97 | and hard line breaks. 98 | - Copyright, trademark, and registered trademark symbols are now correctly 99 | mapped from their ASCII and UTF-8 representations to the output format's 100 | preferred encoding (Issue #1) 101 | - Added documentation on EPUB and HTML stylesheets. 102 | 103 | 104 | Changes in v3.0 (2019-01-04) 105 | ---------------------------- 106 | 107 | - Fixed potential crash bugs in mxmldoc found by fuzzing. 108 | - The `--header` and `--footer` options now support markdown. 109 | - The `mxmldoc` program now sets the EPUB subject ("Programming"). 110 | - Improved EPUB error reporting and output. 111 | - Man page output now uses the ISO date format (yyyy-mm-dd) 112 | - Dropped support for `--framed basename` since frame sets are deprecated in 113 | HTML 5. 114 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | Code of Conduct 2 | =============== 3 | 4 | My goal is to provide quality open source software that everyone can use. 5 | While I may not be able to address every request or accept every contribution 6 | to this project, I will do my best to develop and maintain it for the common 7 | good. As part of the open source community, I expect everyone to: 8 | 9 | - Be friendly and patient. 10 | - Be respectful, even if we disagree. 11 | - Be honest. 12 | - Be accepting of all people. 13 | - Fully explain your concerns, issues, or ideas. 14 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Contributing to mmd 2 | =================== 3 | 4 | codedoc is developed and distributed as open source software under the Apache 5 | License, Version 2.0. Contributions should be submitted as pull requests on 6 | the Github site: 7 | 8 | http://github.com/michaelrsweet/codedoc/pulls 9 | -------------------------------------------------------------------------------- /DOCUMENTATION.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: How to Use the codedoc Utility 3 | author: Michael R Sweet 4 | copyright: Copyright © 2003-2024 by Michael R Sweet 5 | version: 3.7 6 | ... 7 | 8 | Introduction 9 | ============ 10 | 11 | Codedoc is a general-purpose utility which scans HTML, markdown, C, and C++ 12 | source files to produce EPUB, HTML, and man page documentation that can be read 13 | by humans. Unlike popular C/C++ documentation generators like Doxygen or 14 | Javadoc, Codedoc uses in-line comments rather than comment headers, allowing for 15 | more "natural" code documentation. Additional markdown documentation content 16 | can be included to make the generated documentation even more useful and 17 | complete. 18 | 19 | Codedoc is licensed under the Apache License Version 2.0 with an exception to 20 | allow linking against GPL2/LGPL2-only software. See the files "LICENSE" and 21 | "NOTICE" in the source code archive or Git repository for more information. 22 | 23 | 24 | History 25 | ------- 26 | 27 | Codedoc was originally part of the [Mini-XML](https://www.msweet.org/mxml) 28 | project (as "codedoc") and was developed specifically to generate the API 29 | documentation for Mini-XML and [CUPS](https://www.cups.org). It is now much 30 | more general purpose. 31 | 32 | 33 | Running Codedoc 34 | =============== 35 | 36 | Codedoc produces HTML documentation by default. For example, the following 37 | command will scan all of the C source and header files in the current directory 38 | and produce a HTML documentation file called "documentation.html": 39 | 40 | codedoc *.h *.c >documentation.html 41 | 42 | You can also specify an XML file to create which contains all of the information 43 | from the source files. For example, the following command creates an XML file 44 | called "documentation.xml" in addition to the HTML file: 45 | 46 | codedoc documentation.xml *.h *.c >documentation.html 47 | 48 | The `--no-output` option disables the default HTML output: 49 | 50 | codedoc --no-output documentation.xml *.h *.c 51 | 52 | You can then run codedoc again with the XML file alone to generate the HTML 53 | documentation: 54 | 55 | codedoc documentation.xml >documentation.html 56 | 57 | 58 | Creating Man Pages 59 | ------------------ 60 | 61 | The `--man name` option tells codedoc to create a man page instead of HTML 62 | documentation, for example: 63 | 64 | codedoc --man libexample *.h *.c >libexample.3 65 | codedoc --man libexample documentation.xml *.h *.c >libexample.3 66 | codedoc --man libexample documentation.xml >libexample.3 67 | 68 | 69 | Creating EPUB Books 70 | ------------------- 71 | 72 | The `--epub filename.epub` option tells codedoc to create an EPUB book 73 | containing the HTML documentation, for example: 74 | 75 | codedoc --epub documentation.epub *.h *.c 76 | codedoc --epub documentation.epub documentation.xml *.h *.c 77 | codedoc --epub documentation.epub documentation.xml 78 | 79 | 80 | Adding Content and Metadata 81 | --------------------------- 82 | 83 | Codedoc supports several options for adding content and metadata to the 84 | generated documentation: 85 | 86 | - `--author "name"`: Sets the author name 87 | - `--body filename`: Inserts the named file between the table of contents and 88 | API documentation; the file can be markdown, HTML, or man source 89 | - `--copyright "copyright text"`: Sets the copyright string 90 | - `--coverimage filename.png`: Uses the specified cover page image file 91 | - `--css filename.css`: Uses the specified style sheet file (HTML and EPUB 92 | output) 93 | - `--footer filename`: Appends the named file after the API documentation; the 94 | file can be markdown, HTML, or man source 95 | - `--header filename`: Inserts the named file before the table of contents; the 96 | file can be markdown, HTML, or man source 97 | - `--language ll[-LOC]`: Sets the ISO language and locality codes; the default 98 | is "en-US" for US English 99 | - `--section "{name,number}"`: Sets the section/category name (HTML and EPUB 100 | output) or section number (man page output) 101 | - `--title "title text'`: Sets the title text 102 | 103 | 104 | Markdown Extensions 105 | ------------------- 106 | 107 | Codedoc uses the [mmd](https://www.msweet.org/mmd) library for markdown which 108 | mostly conforms to the CommonMark version of markdown syntax with the following 109 | exceptions: 110 | 111 | - Embedded HTML markup and entities are explicitly not supported or allowed; 112 | the reason for this is to better support different kinds of output from the 113 | markdown "source", including XHTML and man pages. 114 | 115 | - Tabs are silently expanded to the markdown standard of four spaces since HTML 116 | uses eight spaces per tab. 117 | 118 | - Some pathological nested link and inline style features supported by 119 | CommonMark like "`******Really Strong Text******`". 120 | 121 | - Support for metadata as used by Jekyll and other web markdown solutions. 122 | 123 | - Support for "`@`" links which resolve to headings within the documentation. 124 | 125 | - Support for "`@@`" links which resolve to literal names such as functions and 126 | types within the documentation. 127 | 128 | - Support for "`::WIDTHxHEIGHT`", "`::WIDTHx`", and "`::xHEIGHT`" in image (ALT) 129 | text to scale images to the specified size. 130 | 131 | - Support syntax highlighting of "c", "cpp", "css", "html", and "xml" in fenced 132 | code text. 133 | 134 | - Support for tables as used by the 135 | [Github Flavored Markdown Spec](https://github.github.com/gfm). 136 | 137 | 138 | Annotating Your C/C++ Code 139 | ========================== 140 | 141 | Codedoc looks for in-line comments to describe the functions, types, and 142 | constants in your code. Codedoc documents all public names it finds in your 143 | source files - any names starting with the underscore character (_) 144 | or names that are documented with the [`@private@`](#-directives-in-comments) 145 | directive are treated as private and are not documented. 146 | 147 | Comments appearing directly before a function or type definition are used to 148 | document that function or type. Comments appearing after argument, definition, 149 | return type, or variable declarations are used to document that argument, 150 | definition, return type, or variable. For example, the following code excerpt 151 | defines a key/value structure and a function that creates a new instance of that 152 | structure: 153 | 154 | ```c 155 | /* A key/value pair. This is used with the 156 | dictionary structure. */ 157 | 158 | struct keyval 159 | { 160 | char *key; /* Key string */ 161 | char *val; /* Value string */ 162 | }; 163 | 164 | /* Create a new key/value pair. */ 165 | 166 | struct keyval * /* New key/value pair */ 167 | new_keyval( 168 | const char *key, /* Key string */ 169 | const char *val) /* Value string */ 170 | { 171 | ... 172 | } 173 | ``` 174 | 175 | Codedoc also knows to remove extra asterisks (\*) from the comment string, so 176 | the comment string: 177 | 178 | ```c 179 | /* 180 | * Compute the value of PI. 181 | * 182 | * The function connects to an Internet server that streams audio of 183 | * mathematical monks chanting the first 100 digits of PI. 184 | */ 185 | ``` 186 | 187 | will be shown as: 188 | 189 | > Compute the value of PI. 190 | > 191 | > The function connects to an Internet server that streams audio of 192 | > mathematical monks chanting the first 100 digits of PI. 193 | 194 | The first paragraph of a comment is used as the short description of an item. 195 | Any subsequent paragraphs are used as the detailed description of an item. 196 | 197 | 198 | @ Directives in Comments 199 | ------------------------ 200 | 201 | Comments can also include the following special `@name ...@` 202 | directive strings: 203 | 204 | - `@body@`: appends the comment to the body text 205 | - `@code text@`: formats the text as code 206 | - `@deprecated@`: flags the item as deprecated to discourage its use 207 | - `@exclude format[,...,format]@`: excludes the item from the 208 | documentation in the specified formats: "all" for all formats, "epub" 209 | for EPUB books, "html" for HTML output, and "man" for man page output 210 | - `@link name@`: creates a hyperlink to the named function, type, etc. 211 | - `@private@`: flags the item as private so it will not be included in the 212 | documentation 213 | - `@since ...@`: flags the item as new since a particular release. The text 214 | following the `@since` up to the closing `@` is highlighted in the generated 215 | documentation, e.g. `@since libexample 1.1@`. 216 | 217 | 218 | Markdown in Comments 219 | -------------------- 220 | 221 | Comments can use a small subset of markdown inline formatting characters: 222 | 223 | - "\`code\`": formats the text as code 224 | - "\*emphasized\*": emphasizes the text (usually italics) 225 | - "\*\*strong\*\*": strongly emphasizes the text (usually boldface) 226 | - "\[text](url)": inserts a named hyperlink 227 | - "\": inserts a hyperlink 228 | - "\\": escapes the character that follows 229 | 230 | In addition, example code can be surrounded by lines containing "\`\`\`": 231 | 232 | ```c 233 | /* 234 | * Example code: 235 | * 236 | * ``` 237 | * foo = get_foo() + get_baz(); 238 | * bar = get_bar() / foo; 239 | * if (bar > 42) 240 | * do_waz(); 241 | * ``` 242 | */ 243 | ``` 244 | 245 | Bulleted lists can be provided using a leading hyphen: 246 | 247 | ```c 248 | /* 249 | * Example list: 250 | * 251 | * - One fish 252 | * - Two fish 253 | * - Red fish 254 | * - Blue fish 255 | */ 256 | ``` 257 | 258 | and block quotes can be provided using the ">" character: 259 | 260 | ```c 261 | /* 262 | * Some sort of documentation... 263 | * 264 | * > Note: This is a block quote that is typically used for special 265 | * > notes to the reader. 266 | */ 267 | ``` 268 | 269 | 270 | EPUB and HTML Stylesheets 271 | ========================= 272 | 273 | Codedoc makes use of a CSS stylesheet for EPUB and HTML output. The default 274 | stylesheet should be usable for both display and printing, but you can override 275 | it using the `--css` option, for example: 276 | 277 | codedoc --epub documentation.epub --css filename.css documentation.xml *.h *.c 278 | 279 | > **Note:** 280 | > 281 | > Since EPUB uses XHTML (which is case-sensitive), your stylesheet should always 282 | > use lowercase element names ("pre", not "PRE", etc.) 283 | 284 | 285 | CSS Classes 286 | ----------- 287 | 288 | The following CSS classes are used to group the sections in the generated 289 | documentation: 290 | 291 | | Class | Description | Usage | 292 | | ------------ | -------------------------------- | -------------------------- | 293 | | body | The body of the documentation | `
` | 294 | | center | Centered text in cell | `` | 295 | | class | A class | `` | 296 | | code | Wrapped monospace code text | `

` | 297 | | constants | A list of constants | `` | 298 | | contents | The table of contents | `

` | 299 | | | (first level) | `
    ` | 300 | | description | Short description | `

    ` | 301 | | | (in table) | `` | 302 | | discussion | Additional description | `

    ` | 303 | | | (title) | `` | 304 | | | (in table) | `` | 305 | | enumeration | An enumeration type | `` | 306 | | footer | The footer of the documentation | `