# Deliminator Core

A source agnostic code documentation generator.


```
not a commment,
lorem ipsum dolor sit amet, consectetur adipiscing elit.
Duis non nulla nec odio tincidunt ultricies.

/**!
* @Example Table -> table: @COL A: 1,1 @COL B: 1,2
*                          @COL A: 2,1 @COL B: 2,2
*
* @Example Code -> code(bash)
*   export TEST="Hello, World!"
*   [[ $TEST == "Hello, World!" ]] && echo "Test passed" || echo "Test failed"
*/!

not a comment,
lorem ipsum dolor sit amet, consectetur adipiscing elit.

/**!
 * @Example Paragraph: Lorem ipsum
 *   dolor sit amet, consectetur adipiscing elit.
 */!
...
```

Related Projects:
    - [Online REPL](https://gitlab.com/ben_goodman/apps/deliminator-repl) | [link](https://apps.ben.website/deliminator-repl)
    - [CLI](https://gitlab.com/ben_goodman/apps/deliminator-cli)



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