My main concern is this breaking for people silently. Probably the best solution would be to compile-error "nodoc" or "ditto" comments to get people to change.

This wasn't broken before though, so I'm not sure we should really "fix" it.

There is likely not much people outside crystal-lang contributors using this undocumented feature @RX14 .

Besides that, in the worst case, nodoc and ditto will be shown as-is in the method description on the HTML doc – not a big deal.

If the behaviour of the compiler is changed, it should raise. I'm not sure this should to be changed at all (at least not right away).

I like changing from ditto to :ditto: in the stdlib docs, but it doesn't need to be enforced by the compiler/docs generator.

@j8r "ditto" is documented, and plenty of people use it.

The reference should better use :ditto: though. But still, it doesn't hurt to support ditto as well.

I was searching in the code @RX14 - doesn't know it was here, my bad. Itmight also be in other places.

OK, for now we can print a warn about the deprecation of ditto and nodoc.

What to do to merge - do I need to add a deprecated notice, what's the standard way?

I think that just like in other parts of Crystal, there should be one way to do things unless there is a benefit to having 2. Just like Crystal has fewer aliases than Ruby, I think making things consistent and making it only work with colons makes it easier to search for, easier to tell that it is "special", and simpler for codebases to have a common way of documenting things, since only one will work.

I like the idea of raising if the comment line contains just the word ditto or just the word nodoc without colons so that people know there was a change and can easily make that change (a find-and-replace would be really simple # nodoc -> # :nodoc:. Piece of cake)

Sounds good.

As an additional enhancement, I'd like that that a comment just has to start with :nodoc: but may contain other content. This allows to actually have documentation (in code) without being included in the public API.

Rebased to include the change of #6627 by @Sija, which addresses the @straight-shoota's comment above.

What's remaining for merge, all's good?

Can this PR be milestoned? This will avoid me to change the TODO: after x.x.x and rebase for each new release.

I'd prefer if this were two commits, one changing ditto to :ditto:, the other changing compiler behaviour. The first one could be merged right away. Maybe that would be a good idea to split the compiler change into a different PR. It feels like that part might need more discussion.

I think we all agree that using the variants with colons is the preferred way. Judging from the approving reactions, it seems also settled that support for non-colon variants should vanish.

It is however unclear if this should be silent, only a warning or a compiler error. And when it should be applied.

I don't like the current implementation, which just prints a message to STDOUT. Warnings tend to be ignored anyway. IIRC it was decided once that the compiler should either work or fail, but don't issue warnings.

I'd be fine with raising or failing silently. Raising for this seems a bit harsh, so I tend to prefer silently ignoring it. The costs of an error are pretty low: You'd have supposedly undocumented features show up in the API docs with a description nodoc, or some features documented as ditto. Both meanings can be expanded by the reader and are relatively easy to spot by maintainers. That's nothing worth raising for.

Maybe the docs generator could issue a warning and/or the formatter detect and adapt usages. The compiler would stop recognizing non-colon variants two releases later.

@straight-shoota that's fine that the compiler doesn't warn before 1.0 stable, but after the release I hope we'll got deprecation warning before having breaking changes like this (despite not-critical, this is only docs).

I've separated in two commits to follow the suggestion of @straight-shoota .
I let the core members deciding what to do next.

@j8r we document them

Using something uncommon like colons directly show us that they are not regular comments.
Other symbols than colons could be used also.

I like more the colon versions. But it's true that unless we validate/parse :<word>: are within the known doc special keywords both are equally (un)safe. The colon version has the change to implement that validation in the future at least.

@asterite I disagree. Using a special syntax highlights that this is a special value with special behaviour. It differentiates these values from regular text. When a method is documented by a single word, it might be confusing whether that is just a description or has some special meaning (is plain super a keyword, or previous?). When we use a specific format (such as wrapping a word in colons) we could even make any similar value that is not a defined keyword a failure.
:inherit: doesn't even need to be placed at the start of a doc comment, it can be surrounded by paragraphs (see #6989) and currently doesn't support the non-colon variant. Without colons this would be really hard to spot as a keyword.

Omitting the colons might not break anything, but IMO it doesn't improve either. It might be a matter of habit, but I like the :nodoc: notation. I'm pretty sure we had previous discussions about this and always preferred the colon variant.

We could possibly consider using a unique format for specifying doc options (see #8353). For example a syntax inspired by JavaDoc tags could work for this. But I think I'd still prefer colon delimited keywords for :nodoc:, :ditto: and :inherit: because they don't define metadata but directly alter the documentation text.

It may be a good idea @straight-shoota .
There are TODO:, NOTE:, we may also have DITTO and NODOC.
There is less noise, as @asterite pointed out, and there are still in highlighted from regular comments.

Just for reference (I'm not saying it's a good or bad idea), I copied ditto from D: https://dlang.org/spec/ddoc.html#parsing

@asterite ditto alone might have been fine to use only the blank word because it is typically the only content of a doc comment. But nodoc can be followed by internal documentation. And finally inherit which can be somewhere inside the doc text. They definitely call for a special syntax to make them stand out.

Let's keep using and encouraging :nodoc:, :ditto: and :inherit:. And eventually stop treating non-colon versions with a deprecation warning.

I just keep what I've done with sed -i -e 's/# ditto/# :ditto:/g' -e 's/# nodoc/# :nodoc:/g' $(find . -name "*.cr") - replacing all ditto/nodoc with :ditto:/:nodoc:.

@RX14, remains your approval.

Thanks @j8r

FYI. I was checking how this was working and it neither outputs the warnings, nor the warning are build with location information to tell the user were to fix the nodoc.