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;
ULONG ulValueUlong = 0;
DWORD dwValueDword = 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]``
+ - <enum-members>
+ - ScopedEnumValue ``[enum class member]``
+ - EnumConstant ``[enum member]``
+ - Constant
+ - Invalid
+ - <user-record-types>
+ - AbstractClass ``[class, struct, pure-virtual present]``
+ - Struct ``[struct]``
+ - Class ``[class, struct]``
+ - Struct ``[class]``
+ - Union ``[union]``
+ - Enum ``[enum, enum class]``
+ - Invalid
+ - <member-variables> - does not cover ``[static, constexpr]``
+ - ``[const]``
+ - ConstantMember
+ - Constant
+ - PrivateMember ``[private]``
+ - ProtectedMember ``[protected]``
+ - PublicMember ``[public]``
+ - Member
+ - Invalid
+ - <parameters>
+ - ConstexprVariable ``[constexpr]``
+ - ``[const]``
+ - ConstantPointerParameter ``[*]``
+ - ConstantParameter
+ - Constant
+ - ParameterPack ``[...]``
+ - PointerParameter ``[*]``
+ - Parameter
+ - Invalid
+ - <variable>
+ - ConstexprVariable ``[constexpr]``
+ - ``[const]``
+ - ClassConstant ``[const, static]``
+ - <file-level-variable>
+ - GlobalConstantPointer ``[const *]``
+ - GlobalConstant ``[const]``
+ - StaticConstant ``[static, const]``
+ - <local-variable>
+ - LocalConstantPointer ``[const *]``
+ - LocalConstant ``[const]``
+ - Constant ``[const]``
+ - <class-level>
+ - ClassMember ``[static]``
+ - <file-level-variable>
+ - GlobalPointer ``[*]``
+ - GlobalVariable
+ - <local-variable>
+ - StaticVariable ``[static]``
+ - LocalPointer ``[*]``
+ - LocalVariable
+ - <function/method-local-variable>
+ - LocalVariable
+ - Variable
+ - <class method>
+ - <ignore-base-class-method-overrides>
+ - ``[constexpr]``
+ - ConstexprMethod
+ - ConstexprFunction
+ - ClassMethod ``[static]``
+ - VirtualMethod ``[virtual]``
+ - PrivateMethod ``[private]``
+ - ProtectedMethod ``[protected]``
+ - PublicMethod ``[public]``
+ - Method
+ - Function
+ - Invalid
+ - <functions>
+ - <ignore ``main()``>
+ - ConstexprFunction ``[constexpr]``
+ - GlobalFunction ``[static method, static function, in any namespace]``
+ - Function
+ - Invalid
+ - <template parameter>
+ - <template-type-parameter>
+ - TypeTemplateParameter
+ - TemplateParameter
+ - Invalid
+ - <template-non-type-parameter>
+ - ValueTemplateParameter
+ - TemplateParameter
+ - Invalid
+ - <template-template-parameter>
+ - 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,
+``<member-variables>`` 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 ``<parameters>`` are each attempted in turn
+against anything identified as a parameter.
+
+The label ``Invalid`` indicates that valid classifications have been exhausted
+for a particular ``<semantic-context>`` and no further attempts will be made to
+classify the identifier in any other context. For example, in the
+``<paramaters>`` semantic context, clang tidy will abort matching after failing
+to resolve the ``Parameter`` classification and a parameter will *not* be
+classified as a ``Variable``.
+
+Example classification
+----------------------
+
+The code snippet below[1]_ serves as an exhaustive example of various
+identifiers the ``readability-identifier-naming`` check is able to classify.
+Each identifier is documented with the list of classifications that apply to
+that identifier, listed in order of resolution. For example, a local pointer
+variable is commented ``// LocalPointer, LocalVariable, Variable`` indicating it
+is first classified as a ``LocalPointer``, then a ``LocalVariable`` and finally
+as a ``Variable``.
+
+.. code-block:: c++
+
+ #include <array>
+ #include <functional>
+ #include <iostream>
+ #include <string>
+
+ // MacroDefinition
+ #define MACRO_DEFINITION 42
+ // MacroDefinition
+ #define MACRO_FUNCTION(x) (void)x
+
+ // Typedef
+ typedef int MyArchaicInt;
+ // TypeAlias
+ using MyContemporaryInt = int;
+
+ // Namespace
+ namespace some_namespace
+ {
+ // InlineNamespace, Namespace
+ inline namespace version_1
+ {
+ } // namespace version_1
+ } // namespace some_namespace
+
+ // AbstractClass, Class, Struct
+ class AbstractClass
+ {
+ public:
+ // Not checked - constructors and destructors must match class name.
+ inline AbstractClass() = default;
+ // Not checked - constructors and destructors must match class name.
+ inline virtual ~AbstractClass() {}
+
+ // PublicMethod, Method, Function
+ void notAbstract();
+
+ // VirtualMethod, PublicMethod, Method, Function
+ virtual void abstractMethod() = 0;
+ };
+
+ // Class, Struct
+ class ClassNaming
+ {
+ // ----------------------
+ // Class member variables
+ // ----------------------
+ public:
+ // ConstexprVariable, ClassConstant, Constant, ClassMember, GlobalConstant, GlobalVariable, Variable
+ constexpr static int public_constexpr_member = 0;
+
+ // ConstantMember, Constant, PublicMember, Member
+ const int public_constant_member = 0;
+
+ // PublicMember, Member
+ int public_member = 0;
+
+ // ClassMember, Member, Variable
+ static int public_static_member;
+
+ // ClassConstant, Constant, GlobalConstant, GlobalVariable, Variable
+ static const int public_static_constant_member = 0;
+
+ protected:
+ // ConstexprVariable, ClassConstant, Constant, ClassMember, GlobalConstant, GlobalVariable, Variable
+ constexpr static int protected_constexpr_member = 0;
+
+ // ConstantMember, Constant, ProtectedMember, Member
+ const int protected_constant_member = 0;
+
+ // ProtectedMember, Member
+ int protected_member_ = 0;
+
+ // ClassMember, Member, Variable
+ static int protected_static_member;
+
+ // ClassConstant, Constant, GlobalConstant, GlobalVariable, Variable
+ static const int protected_static_constant_member = 0;
+
+ private:
+ // ConstexprVariable, ClassConstant, Constant, ClassMember, GlobalConstant, GlobalVariable, Variable
+ constexpr static int private_constexpr_member = 0;
+
+ // ConstantMember, Constant, PrivateMember, Member
+ const int private_constant_member_ = 0;
+
+ // PrivateMember, Member
+ int private_member_ = 0;
+
+ // ClassMember, Member, Variable
+ static int private_static_member;
+
+ // ClassConstant, Constant, GlobalConstant, GlobalVariable, Variable
+ static const int private_static_constant_member = 0;
+
+ // ----------------------
+ // Class methods
+ // ----------------------
+ public:
+ // ConstexprMethod, ConstexprFunction, PublicMethod, Method, Function
+ constexpr int publicConstexprFunc() { return 0; }
+
+ // ClassMethod, PublicMethod, Method, Function
+ static int publicStaticFunc() { return 0; }
+
+ // VirtualMethod, PublicMethod, Method, Function
+ virtual int publicFunc() { return 0; }
+
+ protected:
+ // ConstexprMethod, ConstexprFunction, ProtectedMethod, Method, Function
+ constexpr int protectedConstexprFunc() { return 0; }
+
+ // ClassMethod, ProtectedMethod, Method, Function
+ static int protectedStaticFunc() { return 0; }
+
+ // VirtualMethod, ProtectedMethod, Method, Function
+ virtual int protectedFunc() { return 0; }
+
+ private:
+ // ConstexprMethod, ConstexprFunction, PrivateMethod, Method, Function
+ constexpr int privateConstexprFunc() { return 0; }
+
+ // ClassMethod, PrivateMethod, Method, Function
+ static int privateStaticFunc() { return 0; }
+
+ // VirtualMethod, PrivateMethod, Method, Function
+ virtual int privateFunc() { return 0; }
+ };
+
+ // Static definitions provided for completeness.
+ int ClassNaming::public_static_member = 0;
+ int ClassNaming::protected_static_member = 0;
+ int ClassNaming::private_static_member = 0;
+
+ // Struct, Class
+ struct StructNaming
+ {
+ };
+
+ // Union
+ union UnionNaming
+ {
+ // PublicMember, Member
+ int union_variable = 0;
+ };
+
+ // Enum
+ enum class EnumClass
+ {
+ // ScopedEnumConstant, EnumConstant, Constant
+ EnumClassValue
+ };
+
+ // Enum
+ enum OldEnum
+ {
+ // EnumConstant, Constant
+ OLD_ENUM_VALUE
+ };
+
+ // GlobalFunction, Function
+ // @param str_ptr ConstantPointerParameter, ConstantParameter, PointerParameter, Parameter
+ // @param str ConstantParameter, Parameter
+ // @param ptr_param PointerParameter, Parameter
+ // @param param Parameter
+ int func(std::string *const str_ptr, const std::string &str, int *ptr_param, int param)
+ {
+ return 0;
+ }
+
+ // ---------
+ // Templates
+ // ---------
+
+ // Class, Struct
+ // @tparam Type TypeTemplateParameter, TemplateParameter
+ // @tparam Size ValueTemplateParameter, TemplateParameter
+ template <typename Type, int Size>
+ class ArrayTemplate
+ {
+ public:
+ // PublicMember, Member
+ Type bytes[Size];
+ };
+
+ // GlobalFunction, Function
+ // @tparam Param TypeTemplateParameter, TemplateParameter
+ // @param val Parameter
+ template <typename Param>
+ void templatePrint(const Param &val)
+ {
+ std::cout << val;
+ }
+
+ // GlobalFunction, Function
+ // @tparam Param TypeTemplateParameter, TemplateParameter
+ // @tparam Args TypeTemplateParameter, TemplateParameter
+ // @param val Parameter
+ // @param args ParameterPack, Parameter
+ template <typename Param, typename... Args>
+ void templatePrint(const Param &val, Args... args)
+ {
+ templatePrint(val);
+ std::cout << ' ';
+ templatePrint(args...);
+ }
+
+ // GlobalFunction, Function
+ // @tparam Callable TemplateTemplateParameter, TemplateParameter
+ // @tparam Param TypeTemplateParameter, TemplateParameter
+ // @param callable Parameter
+ // @param arg Parameter
+ template <template <typename> class Callable, typename Param>
+ Param templateTemplateParam(const Callable<Param(const Param &)> &callable, const Param &arg)
+ {
+ return callable(arg);
+ }
+
+ // -------------------------------
+ // Non-class variable declarations
+ // -------------------------------
+
+ // File level variables (global)
+ //
+ // The categorisation of anonymous namespace and named namespace variables is the same as for the global variable
+ // declarations below.
+
+ // ConstexprVariable, GlobalConstant, Constant, GlobalVariable, Variable
+ constexpr int global_constexpr = 0;
+
+ // GlobalConstantPointer, GlobalConstant, Constant, GlobalPointer, GlobalVariable, Variable
+ int *const global_const_ptr = nullptr;
+
+ // GlobalConstant, Constant, GlobalVariable, Variable
+ const int global_const = 0;
+
+ // GlobalConstant, [StaticConstant,] Constant, GlobalVariable, Variable
+ //
+ // StaticConstant does not actually trip for this declaration despite the documentation indicating that it should.
+ // StaticConstant does not appear to trip for anything. Reading the code, it seems that StaticConstant logic is in the
+ // wrong place and the conditions cannot be met.
+ static const int global_static_const = 0;
+
+ // GlobalConstantPointer, GlobalConstant, [StaticConstant,] Constant, GlobalPointer, GlobalVariable, Variable
+ //
+ // See @c global_static_const regarding StaticConstant
+ static int *const global_static_const_ptr = 0;
+
+ // GlobalFunction, Function
+ //
+ // @param seed Parameter
+ int varFunc(int seed = 0)
+ {
+ // ConstexprVariable, LocalConstant, Constant, LocalVariable, Variable
+ constexpr int local_constexpr = 0;
+
+ // LocalConstant, Constant, LocalVariable, Variable
+ const int local_const = 0;
+
+ // LocalConstantPointer, LocalConstant, Constant, LocalPointer, LocalVariable, Variable
+ const int *const local_const_ptr = &local_const;
+
+ // LocalConstant, Constant, LocalVariable, Variable
+ const auto local_lambda = [](int value) { return value; };
+
+ // StaticVariable, LocalVariable, Variable
+ static int static_variable = 0;
+
+ // LocalVariable, Variable
+ int local_variable = seed;
+
+ // LocalPointer, LocalVariable, Variable
+ int *local_variable_ptr = &local_variable;
+
+ return local_lambda(local_constexpr + local_const + *local_const_ptr + static_variable + local_variable +
+ *local_variable_ptr);
+ }
+
+ // -------------------------------
+ // Non-class function declarations
+ // -------------------------------
+
+ // ConstexprFunction, GlobalFunction, Function
+ constexpr int answer()
+ {
+ return 42;
+ }
+
+ // GlobalFunction, Function
+ static int staticFunc()
+ {
+ return 0;
+ }
+
+ namespace
+ {
+ // Function
+ //
+ // Not a GlobalFunction since it is in a namespace.
+ int anonymousFunc()
+ {
+ return 0;
+ }
+ } // namespace
+
+ // GlobalFunction, Function
+ int otherFunc()
+ {
+ return 0;
+ }
+
+.. [1] Source https://gist.github.com/KazNX/693761f2ee7881c120d209f04084e98a
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
