namuol / cod Goto Github PK

A lot of people (myself included) want to use Markdown or other whitespace-sensitive languages within their docs' text blocks.

Text-block indentation currently causes some unexpected problems, mostly due to how indentation is detected in the parser.

The parser needs to ignore any indentation that occurs inside a text block once its indentation level has been established, unless it de-indents from the previously-established indentation level.

Example (indentation shown as ..):

@test
..This is an indent
..  this is not
..I can have any whitespace
..   in this text block
..     so long as it
..  stays within the
.. bounds of
..the previous indentation
..
This is a de-indent.

The resulting value of {"test": "!text": (...)} would appear like so:

This is an indent
  this is not
I can have any whitespace
   in this text block
     so long as it
  stays within the
 bounds of
the previous indentation

Suppose your language only supports single-line comments that start with #.

Your docs might look something like this:

##
# @MyClass
#
#   I can see why some might prefer this.
#
##

But you may also just want this:

/**
 * @MyClass
 *
 *   "It just looks tidier," some might say.
 * 
 */

I'd propose another option called "trim" that is a string to remove from the beginning of any line.

The default should be * and it should always be optional; i.e. this will still work:

/**
 * @MyClass
 *
 *   "It just looks tidier," some might say.
 * 
 */

/**
  @MyClass:property

    But here I just didn't feel like using that style.

*/

It would be nice if the tags remembered what index they started and ended in the source. Then it would be easy to show the source code of tags.

Ciao @namuol!

I wanted to inform you that I'm acknowledging you and Cod in an app I've just published on GitHub (inside another project for now, it's still in Alpha):

• https://github.com/tajmone/PBCodeArcProto/blob/master/_assets/Doxter.pb

The acknowledgments can be found in the (self-generated) documentation (Live HTML link):

• https://htmlpreview.github.io/?https://github.com/tajmone/PBCodeArcProto/blob/master/_assets/Doxter.html#_acknowledgements

Although my app is quite a different beast from yours (not a fish at all), Cod has provided the sparkle of inspiration to find a custom solution to a problem I had been struggling with for quite some time. So I like to give credits where credits are due.

I didn't peak at Cod's source at all, I just took inspiration from its documentation, and the way language agnostic tags were being parsed into regions. That was enough to give me that Eureka! moment where I could see the solution in front of me.

Best regards,

Tristano Ajmone (Italy)

Hi there

Would be interested in maintaining this and using it as a basis for a language-agnostic docgen tool.

What's your status?

The following produces unexpected results:

/**
@list
  @item val1
    text 1
  @item val2
    text 2
*/

Expected results:

{
  "list": {
    "item": [
      {
        "!value": "val1",
        "!text": "text 1"
      },
      {
        "!value": "val2",
        "!text": "text 2"
      }
    ]
  }
}

Actual results:

{
  "list": {
    "item": [
      {
        "!value": "val1",
        "!text": "text 1"
      },
      "val2"
    ]
  }
}

Note: Placing a tag before the text 2 piece yields correct results; that is, this only happens in the case where the second @item is immediately followed by a text block. Furthermore, a value must be specified as well.

These all behave as expected:

/**
@list
  @item val1
    text 1
  @item
    text 2
*/

/**
@list
  @item val1
    text 1
  @item val2
    @tag
    text 2
*/

The ability to re-open tags at their root level so we can do this:

/**
@Something
  @number 42
*/

// Later...

/**
@Something:
  @number 43
  @number 44
  @number 45
*/

...instead of this:

/**
@Something
  @number 42
*/

// Later...

/**
@Something:number 43
@Something:number 44
@Something:number 45
*/