npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

coboldoc

v1.2.0

Published

CLI tool to generate documentation for COBOL

Downloads

63

Readme

Features

  • 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 Microfocus doc standard;

Requirements

  • NodeJS 8+

Installation

$ npm install -g coboldoc

Usage

$ 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
Usage sample
$ 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

Supported Comment Style

COBOLDoc suports free format and Microfocus comment styles. The diff is on how the comment blocks are detected, depending on the line prefix:

  • Free format uses *>*(*)
  • Microfocus uses *>>(>)

Supported annotations

COBOLDoc suports tag or MSDN annotations.

Tag annotations
*>**
*>  Short sample.
*>  @author Bruno Pacheco (https://brunopacheco1.github.io/)
*>  @license LGPL-3.0
*>**
MSDN annotations
*>>  <summary>Short sample function.</summary>
*>>  <remarks>
*>>      first module function accepts <paramref name=\"first-arg\"/> as an arg.
*>>      <seealso cref=\"secondmodulefunction\"/>
*>>  </remarks>

Comment Blocks

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.

File Comment Block

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
*>**
Module/Function Comment Block

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.

...

Supported MSDN Annotation

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>

Supported tags

@author <author>

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
@license <license>

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.
@param {type} <param name>

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
@return {type}

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.
@summary <summary>

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. | 

Support for HTML in-line content

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>

Support for Markdown in-line content

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.

Roadmap

  • 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!