https://github.com/mmomtchev/documentation-polyglot

C++ plugin for documentation.js
https://github.com/mmomtchev/documentation-polyglot

documentation jsdoc node-addon node-addon-api node-addons

Last synced: 7 days ago
JSON representation

C++ plugin for documentation.js

• Host: GitHub
• URL: https://github.com/mmomtchev/documentation-polyglot
• Owner: mmomtchev
• License: isc
• Created: 2021-11-30T19:01:23.000Z (about 3 years ago)
• Default Branch: master
• Last Pushed: 2023-11-30T16:47:45.000Z (about 1 year ago)
• Last Synced: 2024-12-08T07:18:11.201Z (26 days ago)
• Topics: documentation, jsdoc, node-addon, node-addon-api, node-addons
• Language: C++
• Homepage:
• Size: 2.3 MB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# documentation-polyglot.js



  





  The documentation system for modern JavaScript



***When good engineers meet, they discuss algorithms, but when great engineers meet, they discuss documentation***

[![License: ISC](https://img.shields.io/github/license/mmomtchev/documentation-polyglot)](https://github.com/mmomtchev/documentation-polyglot/blob/master/LICENSE)

[![Node.js CI](https://github.com/mmomtchev/documentation-polyglot/actions/workflows/node.js.yml/badge.svg)](https://github.com/mmomtchev/documentation-polyglot/actions/workflows/node.js.yml)

[![codecov](https://codecov.io/gh/mmomtchev/documentation-polyglot/branch/master/graph/badge.svg?token=NUOEAMLXG2)](https://codecov.io/gh/mmomtchev/documentation-polyglot)

# Plugin Notes

This plugin restores the C++ support for `documentation.js`.

**It requires a plugin framework in `documentation.js` that has yet to be merged**. You can install it from here:

```

npm install -D @mmomtchev/documentation

```

It is an improved version of the old `--polyglot` CLI option of `documentation.js` that got axed in 2017.

The project should already be usable.

It uses *dumb* parsing without an AST blindly extracting JSDoc-compliant comment blocks.

I intend to add extensible helpers allowing to extract some (*C++ is notoriously difficult to parse and this aims to be an universal extractor anyways*) information from the C++ code.

# Installation

The module is not yet published

```

npm install -D documentation-polyglot

```

# Usage

Note that enabling `documentation-polyglot` will also enable `--shallow` if this is not already the case.

## Loading via the command-line

```

documentation build --plugin=documentation-polyglot src/*.cpp lib/*.js -f md -o project.md

```

## Loading via a configuration file

```

documentation build --config=project-documentation.yml src/*.cpp lib/*.js -f md -o project.md

```

`project-documentation.yml`:

```yml

toc:

  - Project Headline

plugin:

  - documentation-polyglot

documentation-polyglot:

  extensions: [ .cpp ]

```

## Extracting information from C++ code

An example for extracting names of `Node::Nan` methods

```yml

documentation-polyglot:

  extensions: [ .cpp ]

  infer:

    kind:

      function: [ NAN_METHOD\(.*\) ]

    name: [ NAN_METHOD\s*\((.*)\) ]

```

An `infer` section applies an implicit JSDoc tag to the tag having the section name:

 * with subsections it will apply the subsection name when one of the provided REs matches.

 * with only REs it will apply the first capture group