[PATCH] D126247: `readability-indentifier-naming` resolution order and examples
KazNX created this revision. KazNX added reviewers: whisperity, clang-tools-extra. KazNX added a project: clang-tools-extra. Herald added a subscriber: rnkovacs. Herald added a project: All. KazNX requested review of this revision. Herald added a subscriber: cfe-commits. Added extensive documentation to identify the order in which `readability-identifier-naming` attempts to resolve its classifications. This is followed by an exhaustive code example covering all identifiers commented with their appropriate classifications. This seeks to provide improved information for those seeking to define a particular naming standard. Repository: rG LLVM Github Monorepo https://reviews.llvm.org/D126247 Files: clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst Index: clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst === --- clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst +++ clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst @@ -2742,3 +2742,459 @@ double dValueDouble = 0.0; ULONGulValueUlong = 0; DWORDdwValueDword = 0; + +Resolution order +--- + +The full set of identifier classifications listed above includes some overlap, +where an individual identifier can falling into several classifications. Bellow +is a list of the classifications supported by ``readability-identifier-naming`` +presented in the order in which the classifications are resolved. Some +classifications appear multiple times as they can be checked in different +contexts. The check returns as soon as the first valid classification is +matched. This occurs when the semantics of the identifier match and there is a +valid option for the classification present in the ``.clang-tidy`` file - e.g., +``readability-identifier-naming.AbstractClassCase``. + + - Typedef ``[typedef]`` + - TypeAlias ``[using Alias = ...]`` + - InlineNamespace ``[inline namespace]`` + - Namespace ```[namespace]`` + - + - ScopedEnumValue ``[enum class member]`` + - EnumConstant ``[enum member]`` + - Constant + - Invalid + - + - AbstractClass ``[class, struct, pure-virtual present]`` + - Struct ``[struct]`` + - Class ``[class, struct]`` + - Struct ``[class]`` + - Union ``[union]`` + - Enum ``[enum, enum class]`` + - Invalid + - - does not cover ``[static, constexpr]`` + - ``[const]`` + - ConstantMember + - Constant + - PrivateMember ``[private]`` + - ProtectedMember ``[protected]`` + - PublicMember ``[public]`` + - Member + - Invalid + - + - ConstexprVariable ``[constexpr]`` + - ``[const]`` + - ConstantPointerParameter ``[*]`` + - ConstantParameter + - Constant + - ParameterPack ``[...]`` + - PointerParameter ``[*]`` + - Parameter + - Invalid + - + - ConstexprVariable ``[constexpr]`` + - ``[const]`` + - ClassConstant ``[const, static]`` + - + - GlobalConstantPointer ``[const *]`` + - GlobalConstant ``[const]`` + - StaticConstant ``[static, const]`` + - + - LocalConstantPointer ``[const *]`` + - LocalConstant ``[const]`` + - Constant ``[const]`` + - + - ClassMember ``[static]`` + - + - GlobalPointer ``[*]`` + - GlobalVariable + - + - StaticVariable ``[static]`` + - LocalPointer ``[*]`` + - LocalVariable + - + - LocalVariable + - Variable + - + - + - ``[constexpr]`` + - ConstexprMethod + - ConstexprFunction + - ClassMethod ``[static]`` + - VirtualMethod ``[virtual]`` + - PrivateMethod ``[private]`` + - ProtectedMethod ``[protected]`` + - PublicMethod ``[public]`` + - Method + - Function + - Invalid + - + - + - ConstexprFunction ``[constexpr]`` + - GlobalFunction ``[static method, static function, in any namespace]`` + - Function + - Invalid + - + - + - TypeTemplateParameter + - TemplateParameter + - Invalid + - + - ValueTemplateParameter + - TemplateParameter + - Invalid + - + - TemplateTemplateParameter + - TemplateParameter + - Invalid + - Invalid + +Labels listed in ``<>`` brackets are semantic qualifiers and attempt to +illustrate the semantic context within which clang-tidy resolves the +classification. These are not formal semantic labels, rather labels which +attempt disambiguation within the context of this document. For example, + identifiers that clang tidy is currently looking only at +member variables. + +Items in ``[]`` brackets provide C/C++ keywords and/or decorations relevant to +that particular classification. These must be present in the declaration for +clang-tidy to match the classification. + +List nesting is used to collate classifications which share some semantic +identification - either a logical grouping using ``<>`` or ``[]`` qualifiers - +and are each validated within that same semantic context. That is, a
[PATCH] D126247: [clang-tidy][doc] Document readability-indentifier-naming resolution order and examples
KazNX marked 17 inline comments as done.
KazNX added inline comments.
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2750-2752
+where an individual identifier can fall into several classifications. Below
+is a list of the classifications supported by ``readability-identifier-naming``
+presented in the order in which the classifications are resolved. Some
whisperity wrote:
> So is this resolution order the same for //every Decl//?
Not as I found it. `IdentifierNamingCheck::findStyleKind()` is laid out mostly
in an ordered fashion, but some checks necessarily repeat either in different
context or because of shared semantics. The best example I have is the `struct`
vs `class` relationship. A `struct` will first be idenified as `SK_Struct`, but
if there's no naming for that, then it will try `SK_Class`. Meanwhile, a
`class` does the same thing in the opposite order; first `SK_Class` then
`SK_Struct`.
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2742
double dValueDouble = 0.0;
ULONGulValueUlong = 0;
LegalizeAdulthood wrote:
> Phabricator says there is no context available. Did you generate this diff
> with `git diff -U99 main`?
No sorry. Will fix on next submission.
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2756
+matched. This occurs when the semantics of the identifier match and there is a
+valid option for the classification present in the ``.clang-tidy`` file - e.g.,
+``readability-identifier-naming.AbstractClassCase``.
LegalizeAdulthood wrote:
> Does it have to be in the `.clang-tidy` file, or is it just a matter of
> setting options?
I've changed the wording.
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2772
+ - Class ``[class, struct]``
+ - Struct ``[class]``
+ - Union ``[union]``
LegalizeAdulthood wrote:
> Why is `Struct` listed twice?
This is a reflection of what actually happes. For a `struct`, it tries to
resovle first as a `struct`, then as a `class`. Meanwhile, for a `class` it
tries `class` first then `struct`. Note the accompanying keywords.
This is also addressed in the paragraph above the list.
> Some classifications appear multiple times as they can be checked in different
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2786
+ -
+ - ConstexprVariable ``[constexpr]``
+ - ``[const]``
LegalizeAdulthood wrote:
> I would have expected `ConstExprVariable` instead?
That's not the case I'm seeing in code or in the documentation. See
https://clang.llvm.org/extra/clang-tidy/checks/readability-identifier-naming.html#cmdoption-arg-constexprvariablecase
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2857
+attempt disambiguation within the context of this document. For example,
+ identifiers that clang tidy is currently looking only at
+member variables.
LegalizeAdulthood wrote:
> Eugene.Zelenko wrote:
> > Ditto.
> `identifies`, not `identifiers`
Intentionaly. I'm using the noun, not the verb.
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2880
+
+The code snippet below[1]_ serves as an exhaustive example of various
+identifiers the ``readability-identifier-naming`` check is able to classify.
LegalizeAdulthood wrote:
> Should we be linking to ephemeral gists that can disappear?
I'm changing this link to a full repo.
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:2880
+
+The code snippet below[1]_ serves as an exhaustive example of various
+identifiers the ``readability-identifier-naming`` check is able to classify.
whisperity wrote:
> KazNX wrote:
> > LegalizeAdulthood wrote:
> > > Should we be linking to ephemeral gists that can disappear?
> > I'm changing this link to a full repo.
> Are the contents of the file linked and the one in the documentation here the
> exact same? In that case I think if the author gives rights for LLVM to use
> their work, we can get rid of the link, as it serves no additional value.
Yeah, I'm no expert on all this, but I am the author of both. If I had
submitted a patch first then I've wouldn't have included the link.
To answer directly, the contents has only minor differences.
Comment at:
clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst:3054
+// @param param Parameter
+int func(std::string *const str_ptr, const std::string &str, int
*ptr_param, int param)
+{
LegalizeAdulthood wrote:
> This covers "const pointer", but what about "pointer t
[PATCH] D126247: `readability-indentifier-naming` resolution order and examples
KazNX updated this revision to Diff 432159. KazNX added a comment. Updated to address feedback. - Typo corrections. - Additional declarations. - Changed source reference URL. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D126247/new/ https://reviews.llvm.org/D126247 Files: clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst Index: clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst === --- clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst +++ clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst @@ -2742,3 +2742,468 @@ double dValueDouble = 0.0; ULONGulValueUlong = 0; DWORDdwValueDword = 0; + +Resolution order + + +The full set of identifier classifications listed above includes some overlap, +where an individual identifier can fall into several classifications. Below +is a list of the classifications supported by ``readability-identifier-naming`` +presented in the order in which the classifications are resolved. Some +classifications appear multiple times as they can be checked in different +contexts. The check returns as soon as the first valid classification is +matched. This occurs when the semantics of the identifier match and there is a +valid option for the classification present in the active configuration - e.g., +``readability-identifier-naming.AbstractClassCase``. + + - Typedef ``[typedef]`` + - TypeAlias ``[using Alias = ...]`` + - InlineNamespace ``[inline namespace]`` + - Namespace ``[namespace]`` + - + - ScopedEnumValue ``[enum class member]`` + - EnumConstant ``[enum member]`` + - Constant + - Invalid + - + - AbstractClass ``[class, struct, pure-virtual present]`` + - Struct ``[struct]`` + - Class ``[class, struct]`` + - Struct ``[class]`` + - Union ``[union]`` + - Enum ``[enum, enum class]`` + - Invalid + - - does not cover ``[static, constexpr]`` + - ``[const]`` + - ConstantMember + - Constant + - PrivateMember ``[private]`` + - ProtectedMember ``[protected]`` + - PublicMember ``[public]`` + - Member + - Invalid + - + - ConstexprVariable ``[constexpr]`` + - ``[const]`` + - ConstantPointerParameter ``[*]`` + - ConstantParameter + - Constant + - ParameterPack ``[...]`` + - PointerParameter ``[*]`` + - Parameter + - Invalid + - + - ConstexprVariable ``[constexpr]`` + - ``[const]`` + - ClassConstant ``[const, static]`` + - + - GlobalConstantPointer ``[const *]`` + - GlobalConstant ``[const]`` + - StaticConstant ``[static, const]`` + - + - LocalConstantPointer ``[const *]`` + - LocalConstant ``[const]`` + - Constant ``[const]`` + - + - ClassMember ``[static]`` + - + - GlobalPointer ``[*]`` + - GlobalVariable + - + - StaticVariable ``[static]`` + - LocalPointer ``[*]`` + - LocalVariable + - + - LocalVariable + - Variable + - + - + - ``[constexpr]`` + - ConstexprMethod + - ConstexprFunction + - ClassMethod ``[static]`` + - VirtualMethod ``[virtual]`` + - PrivateMethod ``[private]`` + - ProtectedMethod ``[protected]`` + - PublicMethod ``[public]`` + - Method + - Function + - Invalid + - + - + - ConstexprFunction ``[constexpr]`` + - GlobalFunction ``[static method, static function, in any namespace]`` + - Function + - Invalid + - + - + - TypeTemplateParameter + - TemplateParameter + - Invalid + - + - ValueTemplateParameter + - TemplateParameter + - Invalid + - + - TemplateTemplateParameter + - TemplateParameter + - Invalid + - Invalid + +Labels listed in ``<>`` brackets are semantic qualifiers and attempt to +illustrate the semantic context within which Clang-tidy resolves the +classification. These are not formal semantic labels, rather labels which +attempt disambiguation within the context of this document. For example, + identifiers that clang tidy is currently looking only at +member variables. + +Items in ``[]`` brackets provide C/C++ keywords and/or decorations relevant to +that particular classification. These must be present in the declaration for +Clang-tidy to match the classification. + +List nesting is used to collate classifications which share some semantic +identification - either a logical grouping using ``<>`` or ``[]`` qualifiers - +and are each validated within that same semantic context. That is, all the +classifications listed under are each attempted in turn +against anything identified as a parameter. + +The label ``Invalid`` indicates that valid classifications have been exhausted +for a particular and no further attempts will be made to +classify the identifier in any other context. For example, in the + semantic context, clang tidy will abort matching afte
