-Include descriptive ``\brief`` paragraphs for all public interfaces (public
-classes, member and non-member functions). Explain API use and purpose in
-``\brief`` paragraphs, don't just restate the information that can be inferred
-from the API name. Put detailed discussion into separate paragraphs.
+Include descriptive paragraphs for all public interfaces (public classes,
+member and non-member functions). Don't just restate the information that can
+be inferred from the API name. The first sentence or a paragraph beginning
+with ``\brief`` is used as an abstract. Put detailed discussion into separate
+paragraphs.