StrictDoc Documentation
strictdoc/backend/sdoc_source_code/models/language.py
Source file coverage
Path:
strictdoc/backend/sdoc_source_code/models/language.py
Lines:
114
Non-empty lines:
92
Non-empty lines covered with requirements:
92 / 92 (100.0%)
Functions:
5
Functions covered by requirements:
5 / 5 (100.0%)
1
"""
2
@relation(SDOC-SRS-142, scope=file)
3
"""
4
 
5
from typing import Any, List, Optional, Set
6
 
7
from strictdoc.backend.sdoc_source_code.constants import FunctionAttribute
8
from strictdoc.backend.sdoc_source_code.models.language_item_marker import (
9
    LanguageItemMarker,
10
)
11
from strictdoc.backend.sdoc_source_code.models.source_location import ByteRange
12
from strictdoc.helpers.auto_described import auto_described
13
 
14
 
15
@auto_described
16
class LanguageItem:
17
    def __init__(
18
        self,
19
        *,
20
        parent: Any,
21
        name: str,
22
        display_name: str,
23
        line_begin: int,
24
        line_end: int,
25
        code_byte_range: Optional[ByteRange],
26
        child_functions: List[Any],
27
        markers: List[LanguageItemMarker],
28
        attributes: Set[FunctionAttribute],
29
    ):
30
        """
31
        Create a LanguageItem object.
32
 
33
        A LanguageItem records essential data like name and location of
34
        programming language items from language-aware parsing. It's up to a
35
        StrictDoc language parser what items they want to support.
36
 
37
        For languages that scatter parts of a function over different places
38
        (e.g. declaration and definition in C), the caller is responsible to
39
        create a separate LanguageItem object for each part, where the parts
40
        match on name. Since it's more common to stick documentation to the
41
        declaration part, StrictDoc will automatically find and link
42
        corresponding definition parts. Not vice versa: If definition parts are
43
        documented, only the definition will be linked.
44
 
45
        parent should be set to the SourceFileTraceabilityInfo that corresponds
46
        to the file where the function is defined. Purpose is to provide meta
47
        information like file name and path while the FileTraceabilityIndex is
48
        not yet fully resolved.
49
 
50
        name is an identifier that should be globally unique for a set of
51
        declarations/definitions. Its purpose is to tie declarations and
52
        definitions. It's up to StrictDoc language parsers to define a naming
53
        convention for their language. The convention should follow language
54
        specific notation for qualified names. E.g. in C++, a member bar in
55
        class Foo will be named "Foo:bar(const CanFrame &frame)". It may be
56
        hard to reimplement the full module and naming system of each language,
57
        so naming is best-effort.
58
 
59
        display_name is an identifier used to resolve forward relations from
60
        users to function objects created by language parsers. The display_name
61
        must thus be predictable for users and as unique as possible. It's up
62
        to StrictDoc language parsers to define a naming convention for their
63
        language. The convention should follow language specific notation for
64
        qualified identifiers. E.g. in C++, a member bar in class Foo will be
65
        named "Foo:bar".
66
 
67
        line start/end (1-based) mark first and last line of the definition
68
        block, *without* leading comment lines, if any. Used to jump to and
69
        highlight the function in source file view in case of forward
70
        relations.
71
 
72
        child_functions could store LanguageItem objects that represent nested
73
        functions. It's currently unused and may be removed.
74
 
75
        markers are only needed if the LanguageItem is a declaration function
76
        (C, C++) that shall be automatically linked to the corresponding
77
        definition function, or if it is a test framework function that shall
78
        be automatically linked with requirements and test results. Otherwise,
79
        it can be empty.
80
 
81
        attributes: For example static, declaration, definition. Enables some
82
        special handling, e.g. automatic linking of definitions if the
83
        LanguageItem is a declaration.
84
        """
85
 
86
        assert parent is not None
87
        self.parent = parent
88
 
89
        # Full qualified name.
90
        self.name = name
91
 
92
        self.display_name = display_name
93
 
94
        # Child functions are supported in programming languages that can nest
95
        # functions, for example, Python.
96
        self.child_functions: List[LanguageItem] = child_functions
97
        self.markers: List[LanguageItemMarker] = markers
98
        self.line_begin = line_begin
99
        self.line_end = line_end
100
 
101
        # Not all source code functions have ranges.
102
        # Example: Robot framework files.
103
        self.code_byte_range: Optional[ByteRange] = code_byte_range
104
 
105
        self.attributes: Set[FunctionAttribute] = attributes
106
 
107
    def is_declaration(self) -> bool:
108
        return FunctionAttribute.DECLARATION in self.attributes
109
 
110
    def is_definition(self) -> bool:
111
        return FunctionAttribute.DEFINITION in self.attributes
112
 
113
    def is_public(self) -> bool:
114
        return FunctionAttribute.STATIC not in self.attributes
1 - 114 | entire file