Author: Aaron Ballman Date: 2022-08-31T08:32:58-04:00 New Revision: 5b861743539aa9a1184589647f6e9ce96da8b620
URL: https://github.com/llvm/llvm-project/commit/5b861743539aa9a1184589647f6e9ce96da8b620 DIFF: https://github.com/llvm/llvm-project/commit/5b861743539aa9a1184589647f6e9ce96da8b620.diff LOG: Clarifying the documentation for diagnostic formats; NFC While discussing diagnostic format strings with a GSoC mentee, it became clear there was some confusion regarding how to use them. Specifically, the documentation for %select caused confunsion because it was using %select{}2 and talking about how the integer value must be in the range [0..2], which made it seem like the positional argument was actually specifying the range of acceptable values. I clarified several of the examples similarly, moved some documentation to a more appropriate place, and added some additional information to the %s modifier to point out that %plural exists. Added: Modified: clang/docs/InternalsManual.rst Removed: ################################################################################ diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index 8d18ff01be04..a20fe623a5c8 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -192,13 +192,18 @@ This gives the ``DiagnosticConsumer`` information about what the argument means without requiring it to use a specific presentation (consider this MVC for Clang :). +It is really easy to add format specifiers to the Clang diagnostics system, but +they should be discussed before they are added. If you are creating a lot of +repetitive diagnostics and/or have an idea for a useful formatter, please bring +it up on the cfe-dev mailing list. + Here are the diff erent diagnostic argument formats currently supported by Clang: **"s" format** Example: - ``"requires %1 parameter%s1"`` + ``"requires %0 parameter%s0"`` Class: Integers Description: @@ -206,12 +211,15 @@ Description: diagnostics. When the integer is 1, it prints as nothing. When the integer is not 1, it prints as "``s``". This allows some simple grammatical forms to be to be handled correctly, and eliminates the need to use gross things like - ``"requires %1 parameter(s)"``. + ``"requires %1 parameter(s)"``. Note, this only handles adding a simple + "``s``" character, it will not handle situations where pluralization is more + complicated such as turning ``fancy`` into ``fancies`` or ``mouse`` into + ``mice``. You can use the "plural" format specifier to handle such situations. **"select" format** Example: - ``"must be a %select{unary|binary|unary or binary}2 operator"`` + ``"must be a %select{unary|binary|unary or binary}0 operator"`` Class: Integers Description: @@ -219,7 +227,7 @@ Description: into one common one, without requiring the diff erence to be specified as an English string argument. Instead of specifying the string, the diagnostic gets an integer argument and the format string selects the numbered option. - In this case, the "``%2``" value must be an integer in the range [0..2]. If + In this case, the "``%0``" value must be an integer in the range [0..2]. If it is 0, it prints "unary", if it is 1 it prints "binary" if it is 2, it prints "unary or binary". This allows other language translations to substitute reasonable words (or entire phrases) based on the semantics of the @@ -229,11 +237,11 @@ Description: **"plural" format** Example: - ``"you have %1 %plural{1:mouse|:mice}1 connected to your computer"`` + ``"you have %0 %plural{1:mouse|:mice}0 connected to your computer"`` Class: Integers Description: - This is a formatter for complex plural forms. It is designed to handle even + This is a formatter for complex plural forms. It is designed to handle even the requirements of languages with very complex plural forms, as many Baltic languages have. The argument consists of a series of expression/form pairs, separated by ":", where the first form whose expression evaluates to true is @@ -245,10 +253,10 @@ Description: numeric condition can take one of three forms. * number: A simple decimal number matches if the argument is the same as the - number. Example: ``"%plural{1:mouse|:mice}4"`` + number. Example: ``"%plural{1:mouse|:mice}0"`` * range: A range in square brackets matches if the argument is within the range. Then range is inclusive on both ends. Example: - ``"%plural{0:none|1:one|[2,5]:some|:many}2"`` + ``"%plural{0:none|1:one|[2,5]:some|:many}0"`` * modulo: A modulo operator is followed by a number, and equals sign and either a number or a range. The tests are the same as for plain numbers and ranges, but the argument is taken modulo the number first. Example: @@ -314,11 +322,6 @@ Description: If tree printing is on, the text after the pipe is printed and a type tree is printed after the diagnostic message. -It is really easy to add format specifiers to the Clang diagnostics system, but -they should be discussed before they are added. If you are creating a lot of -repetitive diagnostics and/or have an idea for a useful formatter, please bring -it up on the cfe-dev mailing list. - **"sub" format** Example: _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits