In systems grown over many years and by many developers, comments about such things are nearly worthless, because they can't be trusted. I wouldn't be surprised to see a comment saying "title cannot be null" right above code that explicitly permits null. A comment that lists which exceptions can be thrown is highly suspect, I would probably delete that just to avoid confusion, and make sure that it's obvious from the code instead.

When code has been poorly refactored (I'd count "documentation/comments weren't updated") I find knowing the original intent behind classes and methods to be useful in understanding their mutated design, and how it was arrived at.

Further, handling of the edge cases may have changed, but many of those changes may be bugs in the code to be fixed rather than intentional design changes to be re-documented. When fishing for the cause of a crash, said comment can help verify the existence of a bug, even if it's not the bug you're looking into.

They can also guide the fixing of that bug. This variable shouldn't be null: is that the fault of the callee for not providing a fallback? the caller for violating function preconditions? caller of caller for the same? another class that had it's invariants violated without asserting?

> comments about such things are nearly worthless

The Java ecosystem lives on such comments. I wouldn't use a Java API without "Javadoc" documentation.

I don't endorse this way of developing software. It's profoundly bad -- in a way that comments can't fix.

Types are typically better documentation than comments:

    addCD :: CDCollection -> String -> Maybe String -> NonNegativeInt -> NonNegativeDouble -> Either FailureType CDCollection

This answers all your questions except for "Which related methods are available?" and the anwsers are checked for correctness at compile time!

You could just write a monad instead.

Those sorts of things are useful, but mainly on API edges. They also tend to get outdated pretty quickly in code with even moderate churn.

It would be interesting to be able to link assertions in a method doc with a test, so that the doc export process/IDE will complain if the test ever gets removed (because the API changed).