Chapel: chpldoc 'throws'

[psahabu]

user story

As a Chapel programmer, I want a library's documentation to provide a list of Errors that can be thrown from each function because I want to be able to handle all the potential Errors.

acceptance criteria

• :throws: is a valid keyword on methods in chpldoc, similar to the :return: or :arg name: tags
• All methods marked throws in the standard and package modules are documented with :throws:.

[lydia-duncan]

@bradcray - does the sorting on this issue seem right to you? I'm thinking about my next sprint and realized that this one might have been placed in Backlog before we had strong guidelines about whether that was appropriate or not.

[bradcray]

I think the backlog is appropriate for this one.

[lydia-duncan]

(In case it wasn't clear, we do output throws on functions in chpldoc today, but we don't have a category in the documentation handling for lists of what errors are thrown. I've been interpreting this issue as referring to the latter concept, since the other support was added half a year before this issue was opened)

[bradcray]

My assumption is that if a user reads a library routine's documentation and can't determine what errors s/he might be responsible for catching at the callsite, just knowing that it throws isn't terribly helpful (?).

[lydia-duncan]

Yeah, that's what we were thinking as well. Just making sure that didn't change the answer. I think I'll add this to my next sprint cycle

[bradcray]

I think there's a design question here as to whether the author of the documentation must manually list all the errors it can throw (as they must for the current "returns" section of the documentation) or whether that list would be auto-generated by chpldoc. In either case, the task seems complicated in cases where the routine is passing along an error from a throwing routine that it called.

[lydia-duncan]

My expectation is that it would be manual, but we can (and should) bring it up to the larger group for discussion.

My rationale for this expectation is that no other part of chpldoc requires resolution to run - while it would be handy, it opens a can of worms implementation-wise and it seems like something the author should know ahead of time instead of relying on chpldoc to tell them.

Relatedly, we have expected that the user could write documentation prior to the implementation of the function itself - return statements don't have to be present in the body for the function to be documented with a return type, but such functions would encounter an issue should they get resolved. As an example, the following file is perfectly documentable prior to the implementation of foo's body:

/* Some documentation */
proc foo (): int { }

I think we should treat throws consistently with the return type in this regard.

Of course, the expectation is that the implementation of foo will be complete before the documentation gets distributed but this avoids forcing the programmer into a particular ordering for their work (which might encourage bad design)

[ben-albrecht]

How do other modern languages document the types of errors a function can raise/throw?

I think it would be really convenient to have the option to auto-generate :arg name:, :returns:, and :throw: lists automatically, but this is probably beyond the scope of this particular issue.

[lydia-duncan]

Java defines a @throws tag. Note that the link talks about checked and unchecked exceptions - most exceptions are "checked" (and thus require a try-catch block) but there are some that are not (e.g. RuntimeExceptions). Here's a link with an example usage

I think some Java IDEs will insert clauses for the return type, the arguments, and the exceptions list in their documentation comment, but the descriptions of when these exceptions can occur are usually filled in by the user (and that information is easily grabbed because it is right in the function declaration).

I'll look up the C++ and Python tools, too

[lydia-duncan]

The Python case is a little unclear. I'm seeing raises, raise, except, exception as Sphinx level tags, and "Raises" sections that look like a user convention. The developer documentation talks about .. exception declarations and :exc: tags to link to exceptions. There seem to be a large number of documentation tools for Python and the ones I am most familiar with might be deprecated at this point (at least, the links to them are broken)

[lydia-duncan]

I'm not seeing a mention of exceptions or errors in Doxygen (the C++ tool I am familiar with)

[ben-albrecht]

I think simply enabling users to list the types of errors, and optionally a description of how those errors can get thrown, would be sufficient for now. There's still some open questions about how that should be specified and rendered, however.

Using python's design might be a good starting point, since we already use Sphinx.

[lydia-duncan]

Using python's design might be a good starting point, since we already use Sphinx.

I think the main drawback there is that it would be using a different keyword than we have chosen for our implementation of error handling.

[ben-albrecht]

Using python's design might be a good starting point, since we already use Sphinx.

I think the main drawback there is that it would be using a different keyword than we have chosen for our implementation of error handling.

That's what I meant by starting point. Switching :raise: to :throw: seems like a good first step away from python's design. :)

[lydia-duncan]

I opened https://github.com/chapel-lang/sphinxcontrib-chapeldomain/pull/34 to add this support. A local build of the sphinx domain documentation seemed to indicate that it works and it passes the Travis testing (meaning my changes don't prevent it from building). Once that PR is merged I will probably merge another one which uses it in our normal documentation, just to be extra certain.