Nested block comments

[fricklerhandwerk]

Nested block comments

[hsjobeki]

As a reference jsdoc has the same problem. Here is the 10 year old issue:

jsdoc/jsdoc#821

Many languages seem to just not support nested block comments.

still would be nice if nix did.

Workarounds:

• use html escape sequences (requires some html processing)
• use single line comments
• import from external source in doc-comments (see my nixdoc PR for that)

[FranciscoTGouveia]

Hi, my name is Francisco and I'm a computer science student that is fascinated by the wonders of Nix. With that being said, I would like to start contributing to the project and think that this could be a good first issue for me to tackle. I've already delved into the codebase an think that the problem might be in the lexical analysis (the Flex file at src/libexpr/lexer.l). I've looked into some closed issues and merged PR's and don't find many assigned issues. Could I be assigned to this issue, or issue assignments are not really a part of the project's culture? Thanks in advance!

[fricklerhandwerk]

@FranciscoTGouveia great to have you! I assigned the issue to you as requested, please add or ping me as a reviewer for PRs.

Note that since we're very conservative with evolving the language, we'll have to make sure that the change is strictly additive and doesn't break existing expressions. We may therefore want to add a test that evaluates past Nixpkgs releases.

[roberth]

Concretely, an expression like this may cease to be valid:

# regression.nix
/*
  ignore src/*
*/
1

This instance could be mitigated by requiring whitespace to precede the nested comment.

We can't know the true extent of such issues, because of private code bases.

A simpler solution to the doc comments use case is to recommend that the commented text be unescaped by documentation tooling, according to some rules to be specified. For example, nixdoc could turn *\/ could into */, but a more complete scheme would be desirable.

EDIT: escaped the wrong end

[hsjobeki]

Another idea:

/**
  comment
  /* nested */
**/
1

Then this would work

# regression.nix
/**
  ignore src/*
**/
1

But this would break:

# regression.nix
/**
  oh no :/
*/
1

[fricklerhandwerk]

Apparently I'm ignorant and full of wishful thinking about how computer languages work, but apparently saying a naive thing such as "the longest sequence of characters between /* and */ is a comment" is an instance of greedy matching, which would make parsing a lot less efficient.

[roberth]

I don't know where you got that, but the longest sequence would also ignore 2 in /**/2/**/, so I don't think we want that anyway.
If we do the unescaping thing, we can keep the parsing (or lexing) the same as it is today. Unescaping is quite cheap and can be done on demand.

[fricklerhandwerk]

@roberth agreed, recommending unescaping is the least invasive and simplest thing to do here.