inline doc comments for enum values are incorrectly associated with line below

[superhawk610]

Bug Report

Most Crystal doc comments are written on the line(s) preceding the value they describe:

# this is a doc comment for module Foo
module Foo
  # this is a doc comment for method bar
  def bar
  end
end

However, enum values often have doc comments written inline (though both forms are valid):

module Demo
  enum TopComments
    # docs for A
    A

    # docs for B
    B
  end

  enum InlineComments
    A # docs for A
    B # docs for B
  end
end

Inline comments are incorrectly associated with the following line (as though they'd been written in the standard line-above style):

I'm not well-versed with the compiler's internals, but I'm fairly certain this is a bug in the parser, not the documentation generation. I would expect both forms to work equally, and would like to be able to mix them as well - here's a code sample from libgit2 bindings that uses both in tandem

@[Link("git2")]
lib LibGit
  enum ErrorCode : LibC::Int
    OK        =  0 # No error
    ERROR     = -1 # Generic error
    NOT_FOUND = -3 # Requested object could not be found
    EXISTS    = -4 # Object exists preventing operation
    AMBIGUOUS = -5 # More than one object matches
    BUFS      = -6 # Output buffer too short to hold data

    # USER is a special error that is never generated by `libgit2` code.
    # You can return it from a callback (e.g to stop an iteration) to
    # know that it was generated by the callback and not by `libgit2`.
    USER = -7

    # ...
  end
end

$ crystal -v
Crystal 1.1.1 [6d9a1d583] (2021-07-26)

LLVM: 10.0.1
Default target: x86_64-unknown-linux-gnu

$ uname -a
Linux meridian 4.19.104-microsoft-standard #1 SMP Wed Feb 19 06:37:35 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux

[Blacksmoke16]

I'm pretty sure this isn't a bug, but more of a feature request given I don't think inline comments are supported as far as I know.

[asterite]

Right, and I would prefer not to do that. It's better to have a single unified way for this. Plus it's easier to read if it's at the top, you have more space

[straight-shoota]

It's certainly a bug that trailing line comments are attached as doc comments of the following expression.

Whether trailing line comments are supposed to be doc comments of the expression in the same line is a different question. I agreed to the previous comments in why that wouldn't be a good Idea.

[superhawk610]

If inline doc comments should be discouraged, they should probably be avoided in the language reference (see here).

I think the example I provided above (LibGit::ErrorCode) illustrates how inline comments are both easier to read and more concise - many enum values are nearly-trivially explained, only requiring a few words for docs (the language reference I linked above is another good example of this). This pattern isn't unique to Crystal, either; libgit2 also uses inline comments for most enums (and plenty other C libs as well).

As @straight-shoota says, this can be broken into two issues:

1. (bug) inline enum comments shouldn't be associated with the value on the next line
2. (feature) inline enum comments should be used as doc comments

I think the implementation for (1) will almost certainly cover (2) as well. I'll concede that it's largely a matter of personal preference, but I think that suggests that there's no "right" way and if both can be supported, IMO both should be.

[straight-shoota]

On said page in the language reference, the comments are merely annotations of the code. They're not intended as doc comments.

I think we should stay with the semantics that inline comments are never considered doc comments.