- Generate documentation in Markdown;
- Generate documentation in HTML;
- Generate documentation in MSDN Comment XML;
- Support for in-line HTML content;
- Support for in-line Markdown content;
- Support for MSDN Comment Style;
- Support for Free Format doc standard;
- Support for Micro Focus doc standard;
- NodeJS 8+
$ npm install -g coboldoc
$ coboldoc
_ _ _
___ ___ | |__ ___ | | __| | ___ ___
/ __| / _ \ | '_ \ / _ \ | | / _` | / _ \ / __|
| (__ | (_) | | |_) | | (_) | | | | (_| | | (_) | | (__
\___| \___/ |_.__/ \___/ |_| \__,_| \___/ \___|
Usage: coboldoc <command> [options]
Options:
-o, --output <output directory> The output directory (default: "/home/casa/dev/git/coboldoc")
-f, --format <output file format> Suported output formats: md, html, msdn (default: "md")
-s, --style <comment style> Suported comment styles: free, microfocus (default: "free")
-a, --annotation <comment annotation> Suported comment annotations: tag, msdn (default: "tag")
-v, --version output the version number
-h, --help display help for command
Commands:
generate <files...> generate the documentation
help [command] display help for command
$ coboldoc generate resources/string.cbl resources/keccak.cbl resources/freedialectsample.cbl -o ./doc/
_ _ _
___ ___ | |__ ___ | | __| | ___ ___
/ __| / _ \ | '_ \ / _ \ | | / _` | / _ \ / __|
| (__ | (_) | | |_) | | (_) | | | | (_| | | (_) | | (__
\___| \___/ |_.__/ \___/ |_| \__,_| \___/ \___|
Output directory: ./doc/
Selected format: md
Generating string.cbl documentation... DONE
Generating keccak.cbl documentation... DONE
Generating freedialectsample.cbl documentation... DONE
Generating README.md... DONE
COBOLDoc suports free format and Micro Focus comment styles. The diff is on how the comment blocks are detected, depending on the line prefix:
- Free format uses
*>*(*) - Micro Focus uses
*>>(>)
COBOLDoc suports tag or MSDN annotations.
*>**
*> Short sample.
*> @author Bruno Pacheco (https://brunopacheco1.github.io/)
*> @license LGPL-3.0
*>**
*>> <summary>Short sample function.</summary>
*>> <remarks>
*>> first module function accepts <paramref name=\"first-arg\"/> as an arg.
*>> <seealso cref=\"secondmodulefunction\"/>
*>> </remarks>
COBOLDoc supports the following comment blocks in order to build the documentation.
In essence, COBOLDoc has been tested against COBOL source files written in free-format only, but there shouldn't be restrictions on other COBOL coding formats, if you follow the standards of this tool. During the scanning phase, COBOLDoc ignores leading blank spaces of each line of code.
Anything that describes the file as a whole, will scanned in this kind of comment block, starting and ending with *>** and all internal line starting with *> .
File comment block can be anywhere in the source file, but ideally it should be in the beginning of it.
*>**
*> Short sample.
*> @author Bruno Pacheco (https://brunopacheco1.github.io/)
*> @license LGPL-3.0
*>**
Anything that describes the next line module or function, will scanned in this kind of comment block, starting and ending with *>* and all internal line starting with *> .
Module/Function comment blocks have to preceed a FUNCTION-ID or PROGRAM-ID definition.
...
*>*
*> The description of this module.
*>*
IDENTIFICATION DIVISION.
PROGRAM-ID. anymodule.
...
*>*
*> The description of this function
*> @param {PIC 9} myarg The argument of this function
*> @return {PIC 9} The return of this function
*>*
IDENTIFICATION DIVISION.
FUNCTION-ID. anyfunction.
...
Please, refer to the list below for the see the supported MSDN annotations:
<c><code><example><list><para><param><paramref><remarks><returns><see><seealso><summary>
Defines the author(s) of the source file. This tag will be scanned in a File Comment Block.
Input:
*>**
*> @author Frodo, Sam, Pippin, Merry, Aragorn,
*> Legolas, Gandalf, Gimli, Boromir
*>**
Output in MD:
author: Frodo, Sam, Pippin, Merry, Aragorn, Legolas, Gandalf, Gimli, Boromir
Defines the license of the source file. This tag will be scanned in a File Comment Block.
Input:
*>**
*> @license LGPL-3.0
*>
*> This library is free software; you can redistribute it and/or
*> modify it under the terms of the GNU Lesser General Public
*> License as published by the Free Software Foundation; either
*> version 3.0 of the License, or (at your option) any later version.
*>
*> This library is distributed in the hope that it will be useful,
*> but WITHOUT ANY WARRANTY; without even the implied warranty of
*> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
*> Lesser General Public License for more details.
*>
*> You should have received a copy of the GNU Lesser General Public
*> License along with this library.
*>**
Output in MD:
license: LGPL-3.0 This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3.0 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library.
Defines the parameter or argument of function. This tag will be scanned in a Module/Function Comment Block. The type is not mandatory and accepts anything.
Input:
*>*
*> @param {Any Type} l-myparameter1 A description of l-myparameter1
*> @param {Any Type 2} l-myparameter2 A description of l-myparameter2
*>*
Output in MD:
> *{Any Type}* **l-myparameter1** A description of l-myparameter1
> *{Any Type 2}* **l-myparameter2** A description of l-myparameter2
Defines the return of function. This tag will be scanned in a Module/Function Comment Block. The type is not mandatory and accepts anything.
Input:
*>*
*> @return {Any Type} A description of this function return.
*>*
Output in MD:
> *{Any Type}* A description of this function return.
If you need to add a short text into the Module or Function Summary tables, you can make use of this tag. When it is missing, the general description will be added into Summary table.
Input:
*>*
*> The description of anyfunction1 perhaps is quite too long to be added into the summary table.
*> @summary Short summary of anyfunction1.
*>*
IDENTIFICATION DIVISION.
FUNCTION-ID. anyfunction1.
...
*>*
*> The description of anyfunction2 is not that long.
*>*
IDENTIFICATION DIVISION.
FUNCTION-ID. anyfunction2.
Output in MD:
| Name | Description |
| ----------- | ----------- |
| [anyfunction1](#anyfunction1) | Short summary of anyfunction1. |
| [anyfunction2](#anyfunction2) | The description of anyfunction2 is not that long. |
COBOLDoc support HTML content. If you need any special formating, it should work correctly if it respects HTML syntax.
Input:
*>*
*> The KECCAK module, that uses the Keccak-f[1600] permutation.<br>
*>
*> Date-Written: 2016-05-17<br>
*> Fields in LINKAGE SECTION:<br>
*> <ul>
*> <li>LNK-KECCAK-RATE: The value of the rate r. The rate must be
*> a multiple of 8 bits in this implementation.</li>
*> <li>LNK-KECCAK-CAPACITY: The value of the capacity c.
*> The rate and capacity must have r+c=1600.</li>
*> <li>LNK-KECCAK-INPUT: The input message. </li>
*> <li>LNK-KECCAK-INPUT-BYTE-LEN: The number of input bytes provided
*> in the input message.</li>
*> <li>LNK-KECCAK-DELIMITED-SUFFIX: Bits that will be automatically
*> appended to the end of the input message, as in domain
*> separation.</li>
*> <li>LNK-KECCAK-OUTPUT: The buffer where to store the output. </li>
*> <li>LNK-KECCAK-OUTPUT-BYTE-LEN: The number of output bytes desired.</li>
*> </ul>
*>*
Output in MD:
The KECCAK module, that uses the Keccak-f[1600] permutation.<br> Date-Written: 2016-05-17<br> Fields in LINKAGE SECTION:<br> <ul> <li>LNK-KECCAK-RATE: The value of the rate r. The rate must be a multiple of 8 bits in this implementation.</li> <li>LNK-KECCAK-CAPACITY: The value of the capacity c. The rate and capacity must have r+c=1600.</li> <li>LNK-KECCAK-INPUT: The input message. </li> <li>LNK-KECCAK-INPUT-BYTE-LEN: The number of input bytes provided in the input message.</li> <li>LNK-KECCAK-DELIMITED-SUFFIX: Bits that will be automatically appended to the end of the input message, as in domain separation.</li> <li>LNK-KECCAK-OUTPUT: The buffer where to store the output. </li> <li>LNK-KECCAK-OUTPUT-BYTE-LEN: The number of output bytes desired.</li> </ul>
COBOLDoc support Markdown content. If you need any special formating, it should work correctly if it respects Markdown syntax.
Input:
*>*
*> The KECCAK module, that uses the Keccak-f[1600] permutation.
*> Date-Written: 2016-05-17
*> Fields in LINKAGE SECTION:
*> - LNK-KECCAK-RATE: The value of the rate r. The rate must be
*> a multiple of 8 bits in this implementation.
*> - LNK-KECCAK-CAPACITY: The value of the capacity c.
*> The rate and capacity must have r+c=1600.
*> - LNK-KECCAK-INPUT: The input message.
*> - LNK-KECCAK-INPUT-BYTE-LEN: The number of input bytes provided
*> in the input message.
*> - LNK-KECCAK-DELIMITED-SUFFIX: Bits that will be automatically
*> appended to the end of the input message, as in domain
*> separation.
*> - LNK-KECCAK-OUTPUT: The buffer where to store the output.
*> - LNK-KECCAK-OUTPUT-BYTE-LEN: The number of output bytes desired.
*>*
Output in MD:
The KECCAK module, that uses the Keccak-f[1600] permutation.
Date-Written: 2016-05-17
Fields in LINKAGE SECTION:
- LNK-KECCAK-RATE: The value of the rate r. The rate must be
a multiple of 8 bits in this implementation.
- LNK-KECCAK-CAPACITY: The value of the capacity c.
The rate and capacity must have r+c=1600.
- LNK-KECCAK-INPUT: The input message.
- LNK-KECCAK-INPUT-BYTE-LEN: The number of input bytes provided
in the input message.
- LNK-KECCAK-DELIMITED-SUFFIX: Bits that will be automatically
appended to the end of the input message, as in domain
separation.
- LNK-KECCAK-OUTPUT: The buffer where to store the output.
- LNK-KECCAK-OUTPUT-BYTE-LEN: The number of output bytes desired.
- List of paragraphs in the module/function details view;
- Scan and display changelog (if present);
- Support other structures in COBOL (entries, classes, interfaces...);
Your contribution is always welcome!