In comments used to build API documentation, you should:
-
Explain what the method or property does, why it exists at all, and explain any domain concepts that are not self-evident to the average consumer of your code.
-
List all preconditions for your parameters (cannot be null, must be within a certain range, etc.)
-
List any postconditions that could influence how callers deal with return values.
-
List any exceptions the method may throw (and under what circumstances).
-
If similar methods exist, explain the differences between them.
-
Call attention to anything unexpected (such as modifying global state).
-
Enumerate any side-effects, if there are any.