[llvm] 6aacdd6 - [docs] Document coding standard for error and warning messages

[James Henderson via llvm-commits]

Author: James Henderson
Date: 2020-03-31T12:41:17+01:00
New Revision: 6aacdd6083d841cd4afb47ba184236844021ac46

URL: https://github.com/llvm/llvm-project/commit/6aacdd6083d841cd4afb47ba184236844021ac46
DIFF: https://github.com/llvm/llvm-project/commit/6aacdd6083d841cd4afb47ba184236844021ac46.diff

LOG: [docs] Document coding standard for error and warning messages

In particular, these messages should start with a lower-case letter and
should have no trailing period at the end of the last sentence.

See http://lists.llvm.org/pipermail/llvm-dev/2020-March/140178.html for
context.

Reviewed by: aaron.ballman, hubert.reinterpretcast, rnk, dblaikie

Differential Revision: https://reviews.llvm.org/D76833

Added: 
    

Modified: 
    llvm/docs/CodingStandards.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 9c33f5b2c2ed..15483e5d2798 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -320,6 +320,46 @@ Preferred:
   /// Builds a B-tree in order to do foo.  See paper by...
   void example() { ... }
 
+Error and Warning Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clear diagnostic messages are important to help users identify and fix issues in
+their inputs. Use succinct but correct English prose that gives the user the
+context needed to understand what went wrong. Also, to match error message
+styles commonly produced by other tools, start the first sentence with a
+lower-case letter, and finish the last sentence without a period, if it would
+end in one otherwise. Sentences which end with 
diff erent punctuation, such as
+"did you forget ';'?", should still do so.
+
+For example this is a good error message:
+
+.. code-block:: none
+
+  error: file.o: section header 3 is corrupt. Size is 10 when it should be 20
+
+This is a bad message, since it does not provide useful information and uses the
+wrong style:
+
+.. code-block:: none
+
+  error: file.o: Corrupt section header.
+
+As with other coding standards, individual projects, such as the Clang Static
+Analyzer, may have preexisting styles that do not conform to this. If a
+
diff erent formatting scheme is used consistently throughout the project, use
+that style instead. Otherwise, this standard applies to all LLVM tools,
+including clang, clang-tidy, and so on.
+
+If the tool or project does not have existing functions to emit warnings or
+errors, use the error and warning handlers provided in ``Support/WithColor.h``
+to ensure they are printed in the appropriate style, rather than printing to
+stderr directly.
+
+When using ``report_fatal_error``, follow the same standards for the message as
+regular error messages. Assertion messages and ``llvm_unreachable`` calls do not
+necessarily need to follow these same styles as they are automatically
+formatted, and thus these guidelines may not be suitable.
+
 ``#include`` Style
 ^^^^^^^^^^^^^^^^^^