This page describes the rules for the Returns section of a method or function. The Returns section tells the caller what they get back and what they can rely on. The description’s verb already states what the method does, and the Returns section describes what the value means and which cases the caller doesn’t have to handle.
api-return-001 should API docs In the Returns section, state what the value means and what the caller can rely on, including whether the value can be null, whether an empty collection is returned instead of null, and any ordering guarantee. State the type only when the syntax block doesn’t show it. For a boolean, use the form true if [condition]; false otherwise, with the literals written as in api-param-004.
Examples
true if the file was deleted; false otherwise.true if the file was deleted and false otherwise. (Written around the sentence-start literal.)Rationale
The type indicates what shape the value has, but the caller also needs to know which cases they must handle. Whether the value can be null, what comes back when nothing matches, and the order of the results are three facts that callers often guess wrong. A wrong guess becomes a bug that the documentation could have prevented.