# Deliminator

A source agnostic code documentation generator.

Try it online: [REPL](https://apps.ben.website/deliminator-repl)

```text
/**!
 * @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 

| Lang| Inline| Block |
| --- | --- | ---  |
| rust   | ✅  | ✅ | 
| js/ts  | ✅  | ✅ | 
| sh     | ✅  | n/a | 
| txt    | ✅  | ✅ | 
| yml    | ✅  | n/a | 
| ?      | ✅  | ✅ | 

## Usage 

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

---

Related Projects:
  - [Online REPL (GitLab)](https://gitlab.com/ben_goodman/apps/deliminator-repl)


## CLI

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

```text
┌─────────────┐
│ 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.

```text
           ┐
  #****    ├ 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.

```text
                                                                        ┐
 #   @   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.

```text

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

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

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

Nested tags 1-level deep are also supported.

```text
 # @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.  


| Style | Valid Entry Type | Target | Args | Default Arg |
| --- | --- | --- | --- | --- |
| `h` | any | Tag | `level: Integer` | `2` |
| `code` | Single Line\Multi-Line | Content | `language: String` | `"text"`. |
| `joined` (default) | Multi-Line | Content | - | - |
| `list` | Multi-Line | Content | - | - |
| `olist` | Multi-Line |Content | - | - |
| `table` | Nested | Content | - | - |