Deliminator

A source agnostic code documentation generator.

Try it online: REPL

/**!
 * @Deliminator
 *  A universal documentation generator.
 *
 * @Features -> list
 *  Fast
 *  Versatile
 *
 * @Supported Languages -> table: @Lang: rust  @Inline: ✅ @Block: ✅
 *                                @Lang: js/ts @Inline: ✅ @Block: ✅
 *                                @Lang: sh    @Inline: ✅ @Block: n/a
 *                                @Lang: txt   @Inline: ✅ @Block: ✅
 *                                @Lang: yml   @Inline: ✅ @Block: n/a
 *                                @Lang: ?     @Inline: ✅ @Block: ✅
 *
 * @Usage -> code(bash)
 *  deliminator '*' '/**!' '*/!' --file ./README.md
 */!

Deliminator

A universal documentation generator.

Features

• Fast
• Versatile

Supported Languages

Usage

deliminator '*' '/**!' '*/!' --file ./text.txt

Related Projects:

• Online REPL (GitLab)

CLI

Usage: deliminator [OPTIONS] <COMMENT> [DELIM]...

Arguments:
  <COMMENT>
  [DELIM]...

Options:
  -o, --output <OUTPUT>
  -f, --file <FILE>
  -F, --format <FORMAT>  [default: markdown] [possible values: json, markdown]
  -v, --verbose
  -h, --help             Print help
  -V, --version          Print version

How To Write Your Docs

This is a quick-start guide to writing documentation using Deliminator.

Structuring

Documentation is written in the form of blocks inside your source code file. One block can contain multiple tags, and one source file can contain multiple blocks.

┌─────────────┐
│ file.yml    │
│ ╭╴╴╴╴╴╴╴╴╮  │
│ │block_1 │  │
│ ╰╶╶╶╶╶╶╶╶╯  │
│             │
│ ╭╴╴╴╴╴╴╴╴╮  │
│ │block_2 │  │
│ ╰╶╶╶╶╶╶╶╶╯  │
│             │
│  ...        │
│             │
└─────────────┘

A documentation block starts and ends with a document deliminator. More than one document deliminator can be provided if start and end sequences are diifferent.

           ┐
  #****    ├ Document deliminator - Block starts.
  #        │
  # tag_1  ├ Comment sequence - Block Continues.
  #        │
  #****    ├ Block ends.
           ┘

└──────────┘
  │
  block 1

  ...

Tags are declared as key-value pairs, separated by a colon.

                                                                        ┐
 #   @   Key  :  This is a tag because it starts with the tag-delim.    │
└─┘ └─┘ └───┘   └───────────────────────────────────────────────────┘   │── tag_1
 │   │    │        │                                                    ┘
 │   │    │       Tag Value
 │   │    │
 │   │    Tag Name
 │   │
 │   Tag Deliminator
 │
 Comment Sequence

Tags may also span multiple lines.

 # @Multiline Test: The value of this tag
 #  spans multiple lines.

Alternativley, the colon can be omitted in favor of a new line.

 # @Multiline Test
 #  The value of this tag
 #  spans multiple lines.

Nested tags 1-level deep are also supported.

 # @Root Tag: @Nested Tag 1: foo @Nested Tag 2: bar

Formattiing

Formatting directives can be applied to tags using the @<KEY> -> style (args) : <VALUE> syntax.