tb_lint.rules.naturaldocs package

Submodules

tb_lint.rules.naturaldocs.class_docs module

Class documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper class documentation

class tb_lint.rules.naturaldocs.class_docs.ClassDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check class documentation

Requirements: - Classes must have ‘Class:’ documentation - Documented name must match actual class name

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check class documentation using AST context

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – AST context with class nodes

Returns:

List of violations found

tb_lint.rules.naturaldocs.constraint_docs module

Constraint documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper constraint documentation

class tb_lint.rules.naturaldocs.constraint_docs.ConstraintDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check constraint documentation

Requirements: - Constraints should have ‘define:’ or ‘Variable:’ documentation - Both formats are acceptable per codebase standards

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check constraint documentation using AST context

tb_lint.rules.naturaldocs.file_header module

File header documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper file header documentation

class tb_lint.rules.naturaldocs.file_header.FileHeaderRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for proper file header documentation

Requirements: - File must have ‘File:’ keyword in first 30 lines - Should have ‘Company:’ field (configurable) - Should have ‘Author:’ field with email (configurable)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check file header documentation

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – Not used for this rule

Returns:

List of violations found

class tb_lint.rules.naturaldocs.file_header.CompanyFieldRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for Company field in file header

This is typically a WARNING rather than ERROR

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check for Company field in header

class tb_lint.rules.naturaldocs.file_header.AuthorFieldRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for Author field with email in file header

This is typically a WARNING rather than ERROR

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check for Author field with email

tb_lint.rules.naturaldocs.function_docs module

Function documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper function documentation

class tb_lint.rules.naturaldocs.function_docs.FunctionDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check function documentation

Requirements: - Functions must have ‘Function:’ documentation - Only prototypes (extern) require documentation - Implementations skip checks if prototype exists

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check function documentation using AST context

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – AST context with function nodes

Returns:

List of violations found

tb_lint.rules.naturaldocs.include_guards module

Include guards rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper include guards

class tb_lint.rules.naturaldocs.include_guards.IncludeGuardsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for proper include guards

Requirements: - Format: `ifndef FILENAME_SV - Format: `define FILENAME_SV - Format: `endif // FILENAME_SV (or any comment) - Package files: Include guards are optional

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check for proper include guards

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – Not used for this rule

Returns:

List of violations found

class tb_lint.rules.naturaldocs.include_guards.IncludeGuardFormatRule(config: dict | None = None)

Bases: BaseRule

Rule: Check include guard format details

Separate rule for format warnings (not as severe as missing guards)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check include guard format

tb_lint.rules.naturaldocs.package_docs module

Package documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper package documentation

class tb_lint.rules.naturaldocs.package_docs.PackageDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check package documentation

Requirements: - Packages must have ‘Package:’ documentation - Documented name must match actual package name

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check package documentation using AST context

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – AST context with package nodes

Returns:

List of violations found

tb_lint.rules.naturaldocs.parameter_docs module

Parameter documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper parameter documentation

class tb_lint.rules.naturaldocs.parameter_docs.ParameterDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check parameter documentation

Requirements: - Parameters can be documented with ‘Constant:’ or ‘Property:’ keywords - Documentation is optional for parameters - Skip type parameters in class headers (documented in Parameters: section)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check parameter documentation using AST context

tb_lint.rules.naturaldocs.task_docs module

Task documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper task documentation

class tb_lint.rules.naturaldocs.task_docs.TaskDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check task documentation

Requirements: - Tasks must have ‘Function:’ documentation (NaturalDocs uses Function for tasks) - Only prototypes (extern) require documentation - Implementations skip checks if prototype exists

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check task documentation using AST context

Similar to function checking but for tasks

tb_lint.rules.naturaldocs.typedef_docs module

Typedef documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper typedef documentation

class tb_lint.rules.naturaldocs.typedef_docs.TypedefDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check typedef documentation

Requirements: - Typedefs can be documented with ‘Typedef:’, ‘Type:’, or ‘Variable:’ - Documentation is optional for typedefs (this rule can be configured to WARNING)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check typedef documentation using AST context

tb_lint.rules.naturaldocs.variable_docs module

Variable documentation rule

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Checks for proper variable documentation

class tb_lint.rules.naturaldocs.variable_docs.VariableDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check variable documentation

Requirements: - Variables can be documented with ‘Variable:’ keyword - Documentation is optional for most variables - Only checks member variables (not local variables)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check variable documentation using AST context

Only checks member variables, not local variables

Module contents

NaturalDocs linting rules

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

class tb_lint.rules.naturaldocs.FileHeaderRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for proper file header documentation

Requirements: - File must have ‘File:’ keyword in first 30 lines - Should have ‘Company:’ field (configurable) - Should have ‘Author:’ field with email (configurable)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check file header documentation

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – Not used for this rule

Returns:

List of violations found

class tb_lint.rules.naturaldocs.CompanyFieldRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for Company field in file header

This is typically a WARNING rather than ERROR

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check for Company field in header

class tb_lint.rules.naturaldocs.AuthorFieldRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for Author field with email in file header

This is typically a WARNING rather than ERROR

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check for Author field with email

class tb_lint.rules.naturaldocs.IncludeGuardsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check for proper include guards

Requirements: - Format: `ifndef FILENAME_SV - Format: `define FILENAME_SV - Format: `endif // FILENAME_SV (or any comment) - Package files: Include guards are optional

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check for proper include guards

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – Not used for this rule

Returns:

List of violations found

class tb_lint.rules.naturaldocs.IncludeGuardFormatRule(config: dict | None = None)

Bases: BaseRule

Rule: Check include guard format details

Separate rule for format warnings (not as severe as missing guards)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check include guard format

class tb_lint.rules.naturaldocs.PackageDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check package documentation

Requirements: - Packages must have ‘Package:’ documentation - Documented name must match actual package name

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check package documentation using AST context

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – AST context with package nodes

Returns:

List of violations found

class tb_lint.rules.naturaldocs.ClassDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check class documentation

Requirements: - Classes must have ‘Class:’ documentation - Documented name must match actual class name

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check class documentation using AST context

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – AST context with class nodes

Returns:

List of violations found

class tb_lint.rules.naturaldocs.FunctionDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check function documentation

Requirements: - Functions must have ‘Function:’ documentation - Only prototypes (extern) require documentation - Implementations skip checks if prototype exists

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check function documentation using AST context

Parameters:

• file_path – Path to file being checked

• file_content – Content of the file

• context – AST context with function nodes

Returns:

List of violations found

class tb_lint.rules.naturaldocs.TaskDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check task documentation

Requirements: - Tasks must have ‘Function:’ documentation (NaturalDocs uses Function for tasks) - Only prototypes (extern) require documentation - Implementations skip checks if prototype exists

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check task documentation using AST context

Similar to function checking but for tasks

class tb_lint.rules.naturaldocs.ConstraintDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check constraint documentation

Requirements: - Constraints should have ‘define:’ or ‘Variable:’ documentation - Both formats are acceptable per codebase standards

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check constraint documentation using AST context

class tb_lint.rules.naturaldocs.TypedefDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check typedef documentation

Requirements: - Typedefs can be documented with ‘Typedef:’, ‘Type:’, or ‘Variable:’ - Documentation is optional for typedefs (this rule can be configured to WARNING)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check typedef documentation using AST context

class tb_lint.rules.naturaldocs.VariableDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check variable documentation

Requirements: - Variables can be documented with ‘Variable:’ keyword - Documentation is optional for most variables - Only checks member variables (not local variables)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check variable documentation using AST context

Only checks member variables, not local variables

class tb_lint.rules.naturaldocs.ParameterDocsRule(config: dict | None = None)

Bases: BaseRule

Rule: Check parameter documentation

Requirements: - Parameters can be documented with ‘Constant:’ or ‘Property:’ keywords - Documentation is optional for parameters - Skip type parameters in class headers (documented in Parameters: section)

property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

default_severity() → RuleSeverity

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

check(file_path: str, file_content: str, context: any) → List[RuleViolation]

Check parameter documentation using AST context