Leafdoc Enable use of directive leading character (:fallen

Original issue: https://github.com/Leaflet/Leaflet/issues/5668

Example (using "@" as the leading character like in Leaflet):

/*
 * @class TestLeafdoc
 *
 * this is my text
 * with another line
 * and now testing the "@" symbol
 * this should be after the "&commat;" symbol.
 */

The "and now testing the "@" symbol" line does not appear in the generated HTML output.

Might be interesting detecting the leading character (:fallen_leaf: or @ or whatever) only if it appears at the beginning of the line?

Or warn that it should not be used within the content?

Jul 29 '17 02:07 ghybs

👍 I'd like to document decorators in some TypeScript usage examples soon, at which point I'll need to fix this.

Aug 22 '19 06:08 trusktr

This just bit me. I have the leafdoc directive character set to @, and I was trying to write a doc something like this:

/*
@example

`cat foo.txt | split -d '@'`

*/

The @ in that example caused the line to be treated as a directive, but because there's no actual directive there, there was no output, and the result was that the content of the @example directive was simply undefined.

Aug 25 '19 04:08 trusktr

Thinking to add an escaping feature. I'm thinking of two options:

double up on the leafdoc character in places where it isn't meant to be used as a directive.
- f.e. @@ to cause an @ in the output instead of it being treated as a directive.
```
/*
@example

`cat foo.txt | split -d '@@'`

*/
```
or prefix it with a backslash
- f.e. \@ to cause an @ in the output instead of it being treated as a directive.
```
/*
@example

`cat foo.txt | split -d '\@'`

*/
```

@ghybs Do you have a preference? Or do you imagine some better way to handle it?

Aug 25 '19 04:08 trusktr

Hi @trusktr!

Thank you for taking the lead on this. I also do appreciate that you ask for opinion.

I must admit I am no longer aware of the internals of leafdoc, so I would say just use whatever seems easier to you.

The 2 proposed options are indeed the classic escape conventions (doubling the special character, e.g. like in CSV, and prefixing with a backslash, like in RegEx, which is also used for other special characters). In any case I think the most important would be to highlight it in documentation, since as shown above, there is no single universal convention.

Aug 26 '19 00:08 ghybs

Thinking further about it, while the 2nd option might seem "more recent", it does create a new special backslash character.

Then you end up with the veeery edge case where someone would really want to display \@ and be hit (e.g. should you want to document it...), unless you introduce an extra \\@ case, etc.

Whereas the 1st option keeps the special meaning to the single specified directive character, and can naturally render @@ by doubling eah character (@@@@). Put that way, this option looks simpler to me...

Aug 26 '19 00:08 ghybs

I think you're right! The double directive character seems like a better option.

Aug 29 '19 05:08 trusktr

Enable use of directive leading character (:fallen_leaf: or @) within docstring content