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

[ghybs]

Original issue: Leaflet/Leaflet#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 "@" 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?

[trusktr]

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

[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.

[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?

[ghybs]

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.

[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...

[trusktr]

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