YARD can't handle comments for constants on the same line.

[ojak]

One very common commenting practice is to put comments for constants on the same line as the constant itself. However, this freaks out yard. For example:

# Yard wants comments for constants here
MY_CONSTANT = 1234

MY_BRIEF_CONSTANT = 5678    # However, this is super-common, but
                            # causes all sorts of problems for YARD

One possible solution is to either:
(a) provide a way to customize YARD to handle both cases, or if not,
(b) provide a flag to turn off generation of docs for constants entirely

Any thoughts? Thx.

[lsegal]

I swore that I replied on the mailing list, but it turns out that the message never got sent through (my mail server was having hiccups at the time). This is what I wrote:

YARD does handle comments on the same line for a constant declaration-- it does not, however, handle comments continued after the constant, as in your example. I agree that one comment on the same line is common, but I would challenge the assertion that the example you provided represents a "very common" idiom. I'm sure that form exists (I've certainly seen it before), but I haven't seen it very often, and this is the very first time anybody has explicitly requested for support for this convention inside of YARD-- that certainly says something about how prevalent it is.

Can you explain what "all sort of problems" are being caused when you use that syntax? If you're talking about comment blocks being associated with subsequent constants or methods, you can fix that by simply inserting one extra line of whitespace between the declarations. YARD stops looking for associated comments after 2 lines of whitespace.

As for disabling docs for constants, you can use queries to exclude constants, but that likely is not going to solve the above problem for all cases. yard --query 'type != :constant' would work.

[ojak]

Thx for the response.

Sorry I didn't clarify up front. By "all sorts of problems" I mean the generated docs have comments in the wrong sections, duplication of comments in multiple sections, comments for constants appearing on the wrong constants, etc. Please see the attached screenshot for a detailed view of some of the issues.

As far as whether comments trailing the constants are a "very common" idiom vs not very common, I guess that interpretation is certainly subjective (and probably more up to you since you're the maintainer). I do appreciate that at some level you need to enforce an opinionated commenting style to get Yard to work. However, with regard to the comments after the constants, we've both seen that structure in the wild and I'd suggest that it's common enough to be a handled case? Especially since the multiline following comments are serial by nature (ie. there are no other code blocks or double newlines between successive comment declarations), so it does seem logical that it would be supported.

Anyhow, thanks for the CLI for disabling comments on constants entirely. I hope the screenshot helps.

[lsegal]

As far as whether comments trailing the constants are a "very common" idiom vs not very common, I guess that interpretation is certainly subjective (and probably more up to you since you're the maintainer).

No. This is not subjective. This is based on real data from years of hosting documentation on rubydoc.info for every available RubyGem and tons of GitHub repositories. We've never had one user complain about the lack of support for this syntax in YARD (you are the first person bringing this up). You could argue that none of those users were using YARD, but after 5+ years I would find it extremely surprising that not a single person using the above syntax has used this tool, either directly or via rubydoc.info. Zero people (other than yourself) reporting this issue, after years of use, is data, as far as I'm concerned. Grepping through code would be easy enough if you wanted to get even more data, if the above isn't a satisfactory answer.

Quite simply, there are not enough users of this syntax to make it worth supporting. It is not a simple change to implement; it is actually extremely difficult to implement a heuristic that can reliably detect if the comment lines on your hashes are associated with one another. It may be easy to detect visually, but it's a completely ambiguous grammar to parse; we would have to make all sorts of assumptions that would fail in even more magical ways.

There is also the problem that it is completely unclear if line-suffix comments on a constant are actually meant as documentation for the constant, rather than inline developer comments, or in this case, explaining a specific line in a very contextual way. If we pulled these line-specific comments out into a large docstring, all that context would be lost. In your example for "MY_HASH", the docstring YARD would pull out would have been:

MY_HASH =
  This is the hash This is the value for :one This is the value for :two

    { ... }

That's most likely not what you want.

Finally, there is also a very simple workaround. Namely, just add an extra newline and the above line-suffixed comment block will be ignored. No CLI options or hacking is necessary, just some extra minor formatting to deal with an extremely ambiguous chunk of code. I think that is more than reasonable.

[ojak]

In the interest of making Yard less brittle, is there an "easy" workaround so that double-newlines don't need to be used or is that a deeper issue?

[lsegal]

The easy workaround is: don't use multi-line line-suffix comments. Using the common acceptable practices for documenting code will keep you from shooting yourself in the foot.

In other words, the multi-line line-suffix comments are the brittle thing here, because no documentation tools understand them. RDoc doesn't (RDoc has similar output generation issues, FYI), and YARD doesn't either. Given that not even RDoc understands this syntax, it's safe to say that nobody should be using it.

I'd be curious to see what real-world code needs this format and can't just use a syntax that more documentation tools understand. Rather than using code comments that you can only see in source, you should be writing comments that can be leveraged as documentation.

[ojak]

Well, I've inherited a codebase with hundreds of thousands of lines that has this style used fairly often, which is what started me down this road.

Now, that said, although it's not a way I've typically commented code in the past, I have to admit that after looking at it in the codebase for awhile, I do actually find it to be extremely clear from a stylistic point of view--an improvement maybe.

But at some point, you have to focus on the use-cases you think are most valuable, no argument there.

Anyhow, thanks for the tips and feedback, I appreciate it.

[lsegal]

Following up since I've made a heuristic change that may affect this use case in #798

I'm going to close this issue since it runs amok with the above issue, and a much more common use case.