feat: doxygen supports

Author: Charliechen114514

base/include/base/macro/plain_property.h

@@ -1,3 +1,16 @@
+/**
+ * @file    base/include/base/macro/plain_property.h
+ * @brief   Macro for generating simple property getters and setters.
+ *
+ * Defines the CF_PLAIN_PROPERTY macro which generates getter and setter
+ * methods for a class member variable with a default value.
+ *
+ * @author  N/A
+ * @date    N/A
+ * @version N/A
+ * @since   N/A
+ * @ingroup none
+ */
 #pragma once
 
 #ifndef CF_PLAIN_PROPERTY

base/include/base/weak_ptr/weak_ptr.h

@@ -335,7 +335,7 @@ template <typename T> class WeakPtr {
      *          otherwise returns an invalid WeakPtr.
      *
      * @tparam  Source Source type (base class).
-     * @param  other  WeakPtr to the source object.
+     * @param[in]  other  WeakPtr to the source object.
      *
      * @return        WeakPtr<Derived> pointing to the same object if
      *                the object is of type Derived, otherwise invalid.
@@ -384,12 +384,30 @@ template <typename T> class WeakPtr {
     explicit WeakPtr(T* ptr, internal::WeakReferenceFlagPtr flag) noexcept
         : ptr_(ptr), flag_(std::move(flag)) {}
 
+    /// Raw pointer to the owned object. Ownership: observer; may be nullptr.
     T* ptr_ = nullptr;
+
+    /// Weak reference flag for lifetime tracking. Ownership: shared; may be nullptr.
     internal::WeakReferenceFlagPtr flag_ = nullptr;
 
-    // Allows WeakPtr with different T to access private members (covariance)
+    /**
+     * @brief  Friend declaration for covariance support.
+     *
+     * @tparam U Type parameter for the befriended WeakPtr.
+     *
+     * @since  N/A
+     * @ingroup none
+     */
     template <typename U> friend class WeakPtr;
 
+    /**
+     * @brief  Friend declaration for factory access.
+     *
+     * @tparam U Type parameter for the befriended WeakPtrFactory.
+     *
+     * @since  N/A
+     * @ingroup none
+     */
     template <typename U> friend class WeakPtrFactory;
 };
 

scripts/doxygen/lint.py

@@ -51,9 +51,17 @@
 # ====================== REGEX RULES =========================
 # ============================================================
 
-FIRST_PERSON_PATTERN = re.compile(r"\b(we|our|my)\b|\bI\b(?![/oO])", re.IGNORECASE)
+# Note: 'I' must be case-sensitive to avoid matching loop variable 'i'
+# we/our/my are case-insensitive to catch variants like WE, Our, MY, etc.
 FUTURE_TENSE_PATTERN = re.compile(r"\bwill\b", re.IGNORECASE)
 
+# Compile a case-sensitive pattern for 'I' to avoid matching loop variable 'i'
+# This pattern matches 'I' (uppercase only) as a whole word, except when followed by /, o, or O
+FIRST_PERSON_I_PATTERN = re.compile(r"\bI\b(?![/oO])")
+
+# Pattern for we/our/my (case-insensitive)
+FIRST_PERSON_WE_PATTERN = re.compile(r"\b(?:we|our|my)\b", re.IGNORECASE)
+
 FUNCTION_PATTERN = re.compile(
     r'^\s*(?:template\s*<[^>]*>\s*)?(?:virtual\s+)?(?:inline\s+)?(?:explicit\s+)?(?:static\s+)?(?:constexpr\s+)?(?:consteval\s+)?(?:constinit\s+)?(?:friend\s+)?([\w:<>&\s]+?)(?:\s+const)?\s+(?!if|for|while|switch|return|static_assert|catch|union|struct|class)(\w+)\s*\(([^)]*)\)(?:\s*(?:const|volatile|noexcept(?:\([^)]*\))?|override|final|consteval|constinit)\s*)*(?:\s*=\s*0)?\s*[;{]',
     re.MULTILINE,
@@ -715,6 +723,16 @@ def looks_like_function_call_params(params_str: str) -> bool:
         if not return_type or not return_type.strip():
             continue
 
+        # Skip if return type is ":" - this is a member initializer list, not a function
+        # Example: ": ICFAbstractAnimation(parent) {"
+        if return_type.strip() == ':':
+            continue
+
+        # Skip if return type is "return" - this is a return statement, not a function
+        # Example: "return WeakPtr();"
+        if return_type.strip() == 'return':
+            continue
+
         # Skip if function is inside a @code block (example code)
         if is_in_code_block(func_pos, content):
             continue
@@ -928,7 +946,12 @@ def looks_like_function_call_params(params_str: str) -> bool:
 def check_language_rules(content: str, file: Path) -> List[Violation]:
     violations: List[Violation] = []
 
-    if FIRST_PERSON_PATTERN.search(content):
+    # Check for first-person pronouns
+    # For 'I', use case-sensitive pattern to avoid matching loop variable 'i'
+    if FIRST_PERSON_I_PATTERN.search(content):
+        violations.append(Violation(file, "First-person usage detected"))
+    # For we/our/my, use case-insensitive pattern
+    elif FIRST_PERSON_WE_PATTERN.search(content):
         violations.append(Violation(file, "First-person usage detected"))
 
     if FUTURE_TENSE_PATTERN.search(content):

test/tools/test_doxygen_linter/test_check_function_blocks.py

@@ -305,3 +305,94 @@ def test_multiple_functions(self) -> None:
         # Only second() should have violations
         assert_len(violations, 1)
         assert_equal(violations[0].symbol, "second")
+
+    def test_return_statement_not_matched_as_function(self) -> None:
+        """Test that return statements are not matched as function declarations."""
+        content = """/**
+ * @brief  Dynamically converts Base to Derived.
+ *
+ * @param[in]  other  WeakPtr to the source object.
+ *
+ * @return        WeakPtr<Derived> pointing to the same object.
+ *
+ * @throws        None
+ * @note          The returned WeakPtr shares the same weak reference.
+ * @warning       Always check the returned WeakPtr's validity before use.
+ * @since         0.1
+ * @ingroup       none
+ */
+template <typename Source>
+static WeakPtr DynamicCast(const WeakPtr<Source>& other) noexcept {
+    if (!other.flag_ || !other.flag_->IsAlive()) {
+        return WeakPtr();  // Should not be flagged as missing Doxygen
+    }
+    T* casted = dynamic_cast<T*>(other.ptr_);
+    if (casted) {
+        return WeakPtr(casted, other.flag_);  // Should not be flagged
+    }
+    return WeakPtr();  // Should not be flagged
+}"""
+        violations = lint.check_function_blocks(content, Path("test.h"))
+        # DynamicCast is fully documented, return statements should not cause extra violations
+        assert_len(violations, 0)
+
+    def test_undocumented_function_with_return_statements(self) -> None:
+        """Test that return statements don't create false violations."""
+        content = """
+// Undocumented function
+static WeakPtr CreateWeakPtr() {
+    return WeakPtr();  // Should not be flagged as a separate missing Doxygen
+}
+"""
+        violations = lint.check_function_blocks(content, Path("test.h"))
+        # Only CreateWeakPtr should have a violation, not the return statement
+        assert_len(violations, 1)
+        assert_equal(violations[0].symbol, "CreateWeakPtr")
+
+    def test_member_initializer_list_not_matched_as_function(self) -> None:
+        """Test that member initializer lists are not matched as function declarations."""
+        content = """/**
+ * @brief  Constructor with spring easing preset.
+ *
+ * @param[in] easing Spring preset for physics parameters.
+ * @param[in] parent QObject parent.
+ *
+ * @throws     None
+ * @note       None
+ * @warning    None
+ * @since      0.1
+ * @ingroup    ui_components
+ */
+ICFSpringAnimation(const base::Easing::SpringPreset& easing, QObject* parent = nullptr)
+    : ICFAbstractAnimation(parent) {  # Should not be flagged as a separate function
+    easing_ = easing;
+}"""
+        violations = lint.check_function_blocks(content, Path("test.h"))
+        # Constructor is documented, initializer list should not cause extra violations
+        assert_len(violations, 0)
+
+    def test_constructor_with_return_statement(self) -> None:
+        """Test constructor that contains return statements (for nested helper functions)."""
+        content = """/**
+ * @brief  Default constructor: creates an empty weak reference.
+ * @throws None
+ * @note   None
+ * @warning None
+ * @since  0.1
+ * @ingroup none
+ */
+constexpr WeakPtr() noexcept = default;
+
+/**
+ * @brief  Constructs an empty weak reference from nullptr.
+ * @param[in] nullptr_t The nullptr literal.
+ * @throws None
+ * @note   None
+ * @warning None
+ * @since  0.1
+ * @ingroup none
+ */
+constexpr WeakPtr(std::nullptr_t) noexcept {}"""
+        violations = lint.check_function_blocks(content, Path("test.h"))
+        # Both constructors are documented
+        assert_len(violations, 0)

test/tools/test_doxygen_linter/test_check_language_rules.py

@@ -134,3 +134,46 @@ def test_empty_content(self) -> None:
         content = ""
         violations = lint.check_language_rules(content, Path("test.h"))
         assert_len(violations, 0)
+
+    def test_loop_variable_i_not_flagged(self) -> None:
+        """Test that loop variable 'i' is NOT flagged as first-person."""
+        content = """/**
+ * @brief  Process items in a loop.
+ *
+ * @details Iterates through the array using index i.
+ *
+ * @param[in]  data  The data array.
+ * @return        Processed result.
+ */
+int process(const int* data);"""
+        violations = lint.check_language_rules(content, Path("test.h"))
+        assert_len(violations, 0)
+
+    def test_loop_variables_i_j_k_not_flagged(self) -> None:
+        """Test that common loop variables i, j, k are NOT flagged."""
+        content = """/**
+ * @brief  Nested loop example.
+ *
+ * @details Uses i for outer loop, j for inner loop.
+ *
+ * @return        The sum.
+ */
+int nestedLoop() {
+    for (int i = 0; i < 10; ++i) {
+        for (int j = 0; j < 10; ++j) {
+            for (int k = 0; k < 10; ++k) {
+                // Do something
+            }
+        }
+    }
+    return 0;
+}"""
+        violations = lint.check_language_rules(content, Path("test.h"))
+        assert_len(violations, 0)
+
+    def test_uppercase_i_is_flagged(self) -> None:
+        """Test that uppercase 'I' (first person) IS flagged."""
+        content = "/** I think this works. */"
+        violations = lint.check_language_rules(content, Path("test.h"))
+        assert_len(violations, 1)
+        assert_equal(violations[0].message, "First-person usage detected")