Crystal: Exceptions raised by a method

[Blacksmoke16]

This is sorta similar to #7154, but takes more of the documentation approach versus a compiler feature.

I wanted to start a discussion about a possible improvement that could be made to the auto generated API docs; that shows the exceptions that could be raised by a method.

Currently this can be handled by doing like "# Raises SomeError if xyz" within your api docs. The main problem with this is it would be mixed up in the type's documentation, versus separated out into its own section to improve visibility.

One option would be to have some new keyword within the docs that could be used to say list the possible exceptions after the rest of the documentation.

# RAISES: ParseException When the input is invalid
def some_method

I think ideally this would be parsed out by the doc generator automatically, however that's probably not easily (or at all) doable, so taking a keyword based approach is also fine.

• Yard has https://www.rubydoc.info/gems/yard/file/docs/Tags.md#raise
• PHPDoc has https://docs.phpdoc.org/references/phpdoc/tags/throws.html

tl;dr: Do we think having a built in syntax for rendering exceptions a method may throw is worthwhile?

[straight-shoota]

I'd very much appreciate a standardized approach to document exceptions. Using a structured format would be great for this.

There are a few options though. We could continue with the admonition styled approach or consider something like Java-Doc inspired tags.

Another option is to declare exceptions not in the doc string, but in code, as an annotation:

@[Raises(ParseException, "When the input is invalid")]
def some_method
end

That's already a structured format understood by the compiler, so implementation would be pretty minimal. And it would make it easier to analyze the exceptions. Maybe some kind of linter could validate that all possible exceptions are listed, and maybe even check whether all exceptions are rescued up the line.
This would also be possible when defined inside the doc string, but then it requires understanding of the doc parsing. Annotations are more accessible.

This would be slightly similar to Java's throws clause, which is used to implement checked exceptions. I suppose we won't get that in Crystal, so it won't be a language feature. Java still has a @throws doc tag, though - probably to document unchecked exceptions.

I'm not sure whether using an annotation is the best idea. After all, it's primarily about documentation and we probably won't need to know exceptions at compile time, only in the doc generator (or some kind of analysis tool).

[asterite]

An annotation might be good. The compiler already knows whether a method raises or not, and we could easily enhance it to know which exceptions are thrown. Then checking that this info matches the annotation is easy.

[asterite]

actually, we already have an annotation Raises, but if let's the compiler know a method raises.

[asterite]

Mainly for the main raise method.

[sam0x17]

I really like the idea of doing this automatically/statically. I bet there are places in the standard library where few people know the exceptions that might be thrown. (in other words, automatically generate the "raises" list for each method in the docs without having to manually annotate).

Barring that, the annotation syntax is very clean, easy to implement, and easy to use, and I like it.

[asterite]

It can't be done automatically.

[Blacksmoke16]

The compiler already knows whether a method raises or not, and we could easily enhance it to know which exceptions are thrown.

@asterite I assume by this you mean there could be some like Def.exceptions macro method that returns an array of exception types a given method could raise?

[asterite]

@Blacksmoke16 in theory the compiler could know all the exception types. In practice it doesn't.

[didactic-drunk]

Partial automatically generated documentation may still be useful depending on it's completeness. How much is missing?