From c530b59e5fcf4f2407c0c2eb6c2f160d56e9d3f9 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Fri, 24 Nov 2023 11:57:35 +0000 Subject: [PATCH 1/4] A2-7-3: Exclude function scope declarations --- .../2023-11-24-a2-7-3-remove-function-scope.md | 3 +++ .../rules/A2-7-3/UndocumentedUserDefinedType.ql | 9 +++++++++ cpp/autosar/test/rules/A2-7-3/test.cpp | 17 ++++++++++++++++- 3 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 change_notes/2023-11-24-a2-7-3-remove-function-scope.md diff --git a/change_notes/2023-11-24-a2-7-3-remove-function-scope.md b/change_notes/2023-11-24-a2-7-3-remove-function-scope.md new file mode 100644 index 0000000000..95f6f4364a --- /dev/null +++ b/change_notes/2023-11-24-a2-7-3-remove-function-scope.md @@ -0,0 +1,3 @@ + * `A2-7-3` - reduce false positives by: + - Excluding declarations in function scope. The rationale is that these declarations are not exposed outside the scope of the function. + \ No newline at end of file diff --git a/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql b/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql index 247f3ef2a1..bf86bc0add 100644 --- a/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql +++ b/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql @@ -17,6 +17,14 @@ import cpp import codingstandards.cpp.autosar +private predicate isInFunctionScope(Declaration d) { + // Type declared in function + exists(d.(UserType).getEnclosingFunction()) + or + // Member declared in type which is in function scope + isInFunctionScope(d.getDeclaringType()) +} + /** * A declaration which is required to be preceded by documentation by AUTOSAR A2-7-3. */ @@ -96,6 +104,7 @@ from DocumentableDeclaration d, DeclarationEntry de where not isExcluded(de, CommentsPackage::undocumentedUserDefinedTypeQuery()) and not isExcluded(d, CommentsPackage::undocumentedUserDefinedTypeQuery()) and + not isInFunctionScope(d) and d.getAnUndocumentedDeclarationEntry() = de select de, "Declaration entry for " + d.getDeclarationType() + " " + d.getName() + diff --git a/cpp/autosar/test/rules/A2-7-3/test.cpp b/cpp/autosar/test/rules/A2-7-3/test.cpp index bc174d918d..8e9e180458 100644 --- a/cpp/autosar/test/rules/A2-7-3/test.cpp +++ b/cpp/autosar/test/rules/A2-7-3/test.cpp @@ -160,4 +160,19 @@ template class A2_7_3 final { const std::string kBar{"bar"}; // NON_COMPLIANT }; /// @brief This is the instantiateA2_7_3 documentation -void instantiateA2_7_3() { A2_7_3 instance; } \ No newline at end of file +void instantiateA2_7_3() { A2_7_3 instance; } + +/// Test documentation +void testFunctionScope() { + using my_float = float; + class ClassF { // COMPLIANT - in function scope + public: + int m_x; // COMPLIANT - in function scope + void fTest(); // COMPLIANT - in function scope + class ClassFNested { + public: + int m_nested_x; // COMPLIANT - in function scope + void fNestedTest(); // COMPLIANT - in function scope + }; + }; +} \ No newline at end of file From a37f6c7c835665a7e03c7a12797f6e5012f4ccd8 Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Fri, 24 Nov 2023 13:08:15 +0000 Subject: [PATCH 2/4] Address TODO The workaround is no longer required. --- cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql b/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql index bf86bc0add..a8bfe3b361 100644 --- a/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql +++ b/cpp/autosar/src/rules/A2-7-3/UndocumentedUserDefinedType.ql @@ -50,10 +50,8 @@ class DocumentableDeclaration extends Declaration { declarationType = "member variable" and // Exclude memeber variables in instantiated templates, which cannot reasonably be documented. not this.(MemberVariable).isFromTemplateInstantiation(_) and - // Exclude anonymous lambda functions. - // TODO: replace with the following when support is added. - // not this.(MemberVariable).isCompilerGenerated() - not exists(LambdaExpression lc | lc.getACapture().getField() = this) + // Exclude compiler generated variables, such as those for anonymous lambda functions + not this.(MemberVariable).isCompilerGenerated() } /** Gets a `DeclarationEntry` for this declaration that should be documented. */ From ba247cdc8a786facae7c9d14c76594938fd8495b Mon Sep 17 00:00:00 2001 From: Luke Cartey Date: Tue, 5 Dec 2023 10:45:04 +0000 Subject: [PATCH 3/4] Comments: Update A2-7-3 impl scope. --- rule_packages/cpp/Comments.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/rule_packages/cpp/Comments.json b/rule_packages/cpp/Comments.json index d6364f01d6..7af32f62c1 100644 --- a/rule_packages/cpp/Comments.json +++ b/rule_packages/cpp/Comments.json @@ -70,7 +70,10 @@ "tags": [ "maintainability", "readability" - ] + ], + "implementation_scope": { + "description": "Function scope declarations are excluded from this rule as they are restricted in scope to only a single function." + } } ], "title": "All declarations of 'user-defined' types, static and non-static data members, functions and methods shall be preceded by documentation." From 2b9036b24e09bff3b97c39ef6a7c1c4bca7ed668 Mon Sep 17 00:00:00 2001 From: Luke Cartey <5377966+lcartey@users.noreply.github.com> Date: Wed, 14 Feb 2024 23:39:26 +0000 Subject: [PATCH 4/4] Update change_notes/2023-11-24-a2-7-3-remove-function-scope.md Co-authored-by: Kristen Newbury --- change_notes/2023-11-24-a2-7-3-remove-function-scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/change_notes/2023-11-24-a2-7-3-remove-function-scope.md b/change_notes/2023-11-24-a2-7-3-remove-function-scope.md index 95f6f4364a..cfd50f8ab8 100644 --- a/change_notes/2023-11-24-a2-7-3-remove-function-scope.md +++ b/change_notes/2023-11-24-a2-7-3-remove-function-scope.md @@ -1,3 +1,3 @@ - * `A2-7-3` - reduce false positives by: + * `A2-7-3` - `UndocumentedUserDefinedType.ql`: - Excluding declarations in function scope. The rationale is that these declarations are not exposed outside the scope of the function. \ No newline at end of file