A random thought I had recently, was that it would be good for packages to document exceptions used and raised by their code. Also what logging topics that the package uses.

Maybe a template in scribble for these kind of things?

Related: why does checked exception in Java get a bad rap? It looks like a good idea.

That is my #1 “unpopular” java opinion

In Racket I end up wrapping a function I know will fail with (with-handlers ([exn:fail? values]) ...) so I can figure out a more precise exn predicate.

A few reasons

The main reason checked exceptions in java can be frustrating is that they don’t integrate well with the type system, so libraries that take lambdas get complicated and often don’t bother supporting them. The map and filter operations on java streams don’t allow checked exceptions at all, for example, whereas the corresponding for loop would simply propagate the checked exception requirements to the surrounding code.

For a while, I’ve been pondering an API equivalent of “nutrition facts” labels. It could include details on time and space consumption, exceptions that may be thrown, and other useful domain-specific details, like if a hashing procedure is suitable for cryptographic purposes or what sorts of grammars a parsing framework can accept. This would be an easy way to incorporate RDF into the docs, which I remember seeing an issue about, some time ago.

I got the idea from Wikipedia’s info boxes and how they are tailored for algorithms:

1. No polymorphism

1. Significant annotation burden

1. The presence of runtime exceptions mean you get less of a guarantee than you hope

I think wikipedia in general has some pretty great ideas to steal when it comes to writing reference documentation