The Returns section tells the caller what they get back and what they can count on. The description’s verb already says what the method does; this section says what the value means and which cases the caller does not 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: whether it can be null, whether an empty collection is returned instead of null, and any ordering guarantee. State the type only when the syntax block does not 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 says what shape the value has; the caller also needs to know which cases they must handle. Nullability, the empty case, and ordering are the three facts callers most often guess wrong, and a guess in the wrong direction is a bug that the documentation could have prevented.