tact-lang / tree-sitter-tact

🌳 Tree-sitter grammar for the ⚡ Tact contract programming language
https://tact-lang.org
MIT License
18 stars 0 forks source link

Set injection language for doc comments `///` to use markdown #44

Closed novusnota closed 3 weeks ago

novusnota commented 3 weeks ago

Later, this fact should also be used for LSP-guided highlighting of code comments.

Also, consider getting rid of @see and @since tags in doc comments and instead use pure markdown everywhere. That is, to go from this:

/// ...
/// @see https://docs.tact-lang.org
/// @since Tact 1.X.X

To this:

/// ...
/// * See https://docs.tact-lang.org
/// * Since Tact 1.X.X

Or this:

/// ...
/// See:
/// * https://docs.tact-lang.org
/// * https://docs.tact-lang.org/book/exit-codes
///
/// Available since Tact 1.X.X

P.S.: The info on availability can be moved to the top. P.P.S.: Of course, this should not be detrimental to the parsing speed.

novusnota commented 3 weeks ago

After researching this for a while, I think that it's not practical and barely feasible (only in Neovim) to do so purely in Tree-sitter injection queries.

That's because only Neovim has #offset! directive, and even with it there would be issues with indentation or blank lines in-between sequences of /// comments. And with all that hassle, only Neovim users would get this enhancement.

Therefore, it only makes sense to alter the highlighting of code comments via the LSP. That said, this issue should be closed.

P.S.: Also, the following would probably become the preferred style for documentation comments to move away from any @ tags in them and use markdown all the way through:

/// ...
/// See:
/// * https://docs.tact-lang.org
/// * https://docs.tact-lang.org/book/exit-codes
///
/// Available since Tact 1.X.X

UPD: The best approach is to put "Available since..." on top, right by the end of first paragraph, whatever it may be. And then the link section "See:" at the bottom makes more sense.