add docstrings to the .pyi

Pylance finds these and displays them

Author: DanielT

autosar_data.pyi

@@ -1,3 +1,22 @@
+"""
+Provides functionality to read, modify and write Autosar arxml files,
+both separately and in projects consisting of multiple files.
+
+Classes:
+
+- ArxmlFile
+- AutosarModel
+- AutosarVersion
+- Element
+- ElementType
+- ValidSubElementInfo
+
+Variables:
+
+- __version__
+
+"""
+
 from .autosar_data import *
 from typing import Dict, List, FrozenSet, Literal, TypeAlias, Tuple, Union
 
@@ -10,50 +29,107 @@ ElementContent: TypeAlias = Union[Element, CharacterData]
 VersionSpecification: TypeAlias = Union[AutosarVersion, List[AutosarVersion]]
 
 class ArxmlFile:
+    """
+    Represents a file that is part of an AutosarModel
+    """
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
     filename: str
+    """filename of the arxml file. Must be unique within the model."""
     version: AutosarVersion
-    def check_version_compatibility(self, version: AutosarVersion) -> List[IncompatibleItemError]: ...
+    """Autosar version of the file"""
+    def check_version_compatibility(self, version: AutosarVersion) -> List[IncompatibleItemError]:
+        """
+        check if the elements in the file would be compatible with the given target version.
+        
+        returns a list of compatibility errors, each of which is an IncompatibleElementError, IncompatibleAttributeError or IncompatibleAttributeValueError
+        """
+        ...
     model: AutosarModel
+    """the autosar data model which this file is part of"""
     elements_dfs: ArxmlFileElementsDfsIterator
-    def serialize(self) -> str: ...
+    """dfs iterator over all elements in this file"""
+    def serialize(self) -> str:
+        """serialize the the file to a string. This string can be loaded as valid arxml if is written to disk."""
+        ...
     xml_standalone: bool
+    """contains the xml standalone attribute (if any) in the xml file header"""
 
 class ArxmlFileElementsDfsIterator:
+    """
+    A depth first search iterator over all elements contained in the file that created this iterator
+    """
     def __iter__(self) -> ArxmlFileElementsDfsIterator: ...
     def __next__(self) -> Tuple[int, Element]: ...
 
 class Attribute:
+    """
+    An attribute on an element
+    """
     attrname: AttributeName
+    """name of this attribute"""
     content: CharacterData
+    """content of the attribute - this data can be free-form text, a pre-defined enum value (str), or very rarely a float or int"""
 
 class AttributeIterator:
+    """
+    Iterates over all attributes on an element
+    """
     def __iter__(self) -> AttributeIterator: ...
     def __next__(self) -> Attribute : ...
 
 class AutosarDataError(Exception):
     pass
 
 class AutosarModel:
+    """
+    Autosar data model. It contains all elements.
+    """
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
-    def create_file(self, filename: str, version: AutosarVersion) -> ArxmlFile: ...
-    def load_buffer(self, buffer: str, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]: ...
-    def load_file(self, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]: ...
-    def remove_file(self, arxmlfile: ArxmlFile) -> None: ...
-    def serialize_files(self) -> Dict[str, str]: ...
-    def write(self) -> None: ...
+    def create_file(self, filename: str, version: AutosarVersion) -> ArxmlFile:
+        """create a new file in the model"""
+        ...
+    def load_buffer(self, buffer: str, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]:
+        """load a buffer (string) as arxml"""
+        ...
+    def load_file(self, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]:
+        """load a file as arxml"""
+        ...
+    def remove_file(self, arxmlfile: ArxmlFile) -> None:
+        """remove a file from the model. Any elements belonging exclusively to that file will also be removed."""
+        ...
+    def serialize_files(self) -> Dict[str, str]:
+        """serialize all files individually, to generate a dict(filename, serialized content),"""
+        ...
+    def write(self) -> None:
+        """write all files in the model to disk"""
+        ...
     files: List[ArxmlFile]
+    """a list of ArxmlFile objects containing all files in the model"""
     root_element: Element
-    def get_element_by_path(self, autosar_path: str) -> Element: ...
+    """The root element of the model, <AUTOSAR>"""
+    def get_element_by_path(self, autosar_path: str) -> Element:
+        """get an identifiable element in the model by its Autosar path"""
+        ...
     elements_dfs: ElementsDfsIterator
-    def sort(self) -> None: ...
+    """depth first dearch iterator over all elements in the model, regardless of their association with a file"""
+    def sort(self) -> None:
+        """sort the entire model in place. Takes all ordering constraints into account."""
+        ...
     identifiable_elements: List[str]
-    def get_references_to(self, target_path: str) -> List[Element]: ...
-    def check_references(self) -> List[Element]: ...
+    """List of all paths of identifiable elements in the model"""
+    def get_references_to(self, target_path: str) -> List[Element]:
+        """get all reference elements which refer to the given Autosar path"""
+        ...
+    def check_references(self) -> List[Element]:
+        """check all references in the model and return a list of elements containing invalid references"""
+        ...
 
 class AutosarVersion:
+    """
+    A version of the Autosar standard
+    """
     def __new__(cls, verstring: str) -> AutosarVersion: ...
     # this is the stupid result of method used by PyO3 to translate Rust enums
     Autosar_4_0_1: AutosarVersion
@@ -77,102 +153,226 @@ class AutosarVersion:
     Autosar_00051: AutosarVersion
 
 class ContentType:
+    """
+    The content type of an element
+    """
     # this is the stupid result of method used by PyO3 to translate Rust enums
     Elements: ContentType
     CharacterData: ContentType
     Mixed: ContentType
 
 class Element:
+    """
+    An element in the Autosar data model
+    """
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
     def serialize(self) -> str: ...
     parent: Element
+    """reference to the parent of this element"""
     element_name: ElementName
+    """ElementName of this element, e.g. AUTOSAR or AR-PACKAGE"""
     element_type: ElementType
+    """Reference to the element type of the element in the specification"""
     item_name: str
+    """item name of an identifiable element, or None for elements which are not identifiable.
+
+    Setting this value renames the element and updates all references to it.
+    """
     is_identifiable: bool
+    """true if the element is identifiable, false otherwise"""
     is_reference: bool
+    """true if the element can contain a reference to another element"""
     path: str
+    """the full autosar path of an identifiable element"""
     model: AutosarModel
+    """reference to the model containing this element"""
     content_type: ContentType
-    def create_sub_element(self, element_name: ElementName) -> Element: ...
-    def create_sub_element_at(self, element_name: ElementName, position: int) -> Element: ...
-    def create_named_sub_element(self, element_name: ElementName, item_name: str) -> Element: ...
-    def create_named_sub_element_at(self, element_name: ElementName, item_name: str, position: int) -> Element: ...
-    def create_copied_sub_element(self, other: Element) -> Element: ...
-    def create_copied_sub_element_at(self, other: Element, position: int) -> Element: ...
-    def move_element_here(self, move_element: Element) -> Element: ...
-    def move_element_here_at(self, move_element: Element, position: int) -> Element: ...
-    def remove_sub_element(self, element: Element) -> None: ...
+    """content type of the element: character data (<X>some text</X>), elements (<X><Y></Y></X>), or Mixed"""
+    def create_sub_element(self, element_name: ElementName) -> Element:
+        """create a sub element under this element with the given ElementName"""
+        ...
+    def create_sub_element_at(self, element_name: ElementName, position: int) -> Element:
+        """create a sub element under this element with the given ElementName at a specific position"""
+        ...
+    def create_named_sub_element(self, element_name: ElementName, item_name: str) -> Element:
+        """create a named sub element under this element with the given ElementName"""
+        ...
+    def create_named_sub_element_at(self, element_name: ElementName, item_name: str, position: int) -> Element:
+        """create a named sub element under this element with the given ElementName at a specific position"""
+        ...
+    def create_copied_sub_element(self, other: Element) -> Element:
+        """create a copy of some other element (with all of its children) as a child of this element"""
+        ...
+    def create_copied_sub_element_at(self, other: Element, position: int) -> Element:
+        """create a copy of some other element (with all of its children) as a child of this element at the given position"""
+        ...
+    def move_element_here(self, move_element: Element) -> Element:
+        """move an element from somewhere else in this model or from another model to become a child element"""
+        ...
+    def move_element_here_at(self, move_element: Element, position: int) -> Element:
+        """move an element from somewhere else in this model or from another model to become a child element at the given position"""
+        ...
+    def remove_sub_element(self, element: Element) -> None:
+        """remove a sub element and all of its content"""
+        ...
     reference_target: Element
-    def get_sub_element(self, name_str: str) -> Element: ...
-    def get_sub_element_at(self, position: int) -> Element: ...
+    """returns the target of the reference, if the element contains a reference"""
+    def get_sub_element(self, name_str: str) -> Element:
+        """get a sub element by its element name. If there are several then this returns the first of them"""
+        ...
+    def get_sub_element_at(self, position: int) -> Element:
+        """get an element by its position among the content of this element"""
+        ...
     position: int
+    """the position of this element in the content of its parent"""
     sub_elements: ElementsIterator
+    """an iterator over all sub elements in the content of this element. It skips character data content items"""
     elements_dfs: ElementsDfsIterator
+    """dpeth first search iterator for this element and all of its sub elements"""
     character_data: CharacterData
-    def remove_character_data(self) -> None: ...
-    def insert_character_content_item(self, chardata: str, position: int) -> None: ...
-    def remove_character_content_item(self, position: int) -> None: ...
+    """character content of this element, if any. For elements with ContentType=Element, or empty elements this is None"""
+    def remove_character_data(self) -> None:
+        """remove the character data"""
+        ...
+    def insert_character_content_item(self, chardata: str, position: int) -> None:
+        """for elements with ElementType mixed, this allows character data to be inserted at any point in the content of this element"""
+        ...
+    def remove_character_content_item(self, position: int) -> None:
+        """remove one character content item from the given position"""
+        ...
     content_item_count: int
+    """number of content items (character data and/or sub elements)"""
     content: ElementContentIterator
+    """iterator over all content of this element"""
     attributes: AttributeIterator
-    def attribute_value(self, attrname: AttributeName) -> CharacterData: ...
-    def set_attribute(self, attrname: AttributeName, chardata: CharacterData) -> None: ...
-    def set_attribute_string(self, attrname: AttributeName, value: str) -> None: ...
-    def remove_attribute(self, attrname: AttributeName) -> None: ...
-    def sort(self) -> None: ...
-    def list_valid_sub_elements(self) -> List[ValidSubElementInfo]: ...
+    """iterator over all attributes of this element"""
+    def attribute_value(self, attrname: AttributeName) -> CharacterData:
+        """get the attribute value of a specific attribute. Returns None if that attribute is not set"""
+        ...
+    def set_attribute(self, attrname: AttributeName, chardata: CharacterData) -> None:
+        """set the given attribute to the provided value. If the attribute is valid for this element it will be created or modified as needed."""
+        ...
+    def set_attribute_string(self, attrname: AttributeName, value: str) -> None:
+        """like set_attribute, but the input will be converted to the target data type as needed"""
+        ...
+    def remove_attribute(self, attrname: AttributeName) -> None:
+        """remove an attribute from the element"""
+        ...
+    def sort(self) -> None:
+        """sort this element and all of its sub elements"""
+        ...
+    def list_valid_sub_elements(self) -> List[ValidSubElementInfo]:
+        """provide information about valid sub elements as a list of ValidSubElementInfo"""
+        ...
     file_membership: Tuple[bool, FrozenSet[ArxmlFile]]
-    def add_to_file(self, file: ArxmlFile) -> None: ...
-    def remove_from_file(self, file: ArxmlFile) -> None: ...
+    """file membership information: the tuple (is_local, set(ArxmlFile)) tells if there is a restriction to file membership attached to this element, and which files the element is part of"""
+    def add_to_file(self, file: ArxmlFile) -> None:
+        """add the element to a file. if necessary all parent elements of this element also become part of the file"""
+        ...
+    def remove_from_file(self, file: ArxmlFile) -> None:
+        """remove this element from a file. Does not affect parent elements. When an element is no longer part of any file it is deleted."""
+        ...
     xml_path: str
+    """a path listing all xml elements from the root of the model to the element. This is intended for display. e.g. in error messages"""
 
 class ElementContentIterator:
+    """
+    Iterates over all content in an element
+
+    Content items an be sub elements or character data
+    """
     def __iter__(self) -> ElementContentIterator: ...
     def __next__(self) -> ElementContent: ...
 
 class ElementType:
+    """
+    Type of an Element in the specification
+    """
     is_named: bool
+    """Elements of this type must have a SHORT-NAME"""
     is_ref: bool
+    """elements of this type must contain an autosar path in their character data, and have a DEST attribute"""
     is_ordered: bool
+    """ordered elements may not be sorted, since the sub element order is semantically meaningful"""
     splittable: List[AutosarVersion]
-    def splittable_in(self, version: AutosarVersion) -> bool: ...
-    def reference_dest_value(self, target: ElementType) -> EnumItem: ...
-    def find_sub_element(self, target_name: ElementName, version: VersionSpecification) -> ElementType: ...
+    """a list of AutosarVersions in which this element is splittable"""
+    def splittable_in(self, version: AutosarVersion) -> bool:
+        """is this element splittable in a particular AutosarVersion"""
+        ...
+    def reference_dest_value(self, target: ElementType) -> EnumItem:
+        """helper to determine the correct value for the DEST attribute when setting a reference"""
+        ...
+    def find_sub_element(self, target_name: ElementName, version: VersionSpecification) -> ElementType:
+        """find the ElementType of the named sub element in the specification of this ElementType"""
+        ...
 
 class ElementsDfsIterator:
+    """
+    Dpeth first search iterator starting at the element which created the iterator
+    """
     def __iter__(self) -> ElementsDfsIterator: ...
     def __next__(self) -> Tuple[int, Element]: ...
 
 class ElementsIterator:
+    """
+    Iterator over all sub elements of an element
+    """
     def __iter__(self) -> ElementsIterator: ...
     def __next__(self) -> Element: ...
 
 class IncompatibleAttributeError:
+    """
+    Information about an attribute that is incompatible with a given target version
+    """
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
     element: Element
+    """Element which contains the incompatible attribute"""
     attribute: AttributeName
+    """Incompatible attribute"""
     allowed_versions: List[AutosarVersion]
+    """list of versions in which the attribute is permitted on this element"""
 
 class IncompatibleAttributeValueError:
+    """
+    Information about an attribute value that is incompatible with a given target version
+    """
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
     element: Element
+    """Element which contains the incompatible attribute value"""
     attribute: AttributeName
+    """Attribute which contains the invalid value"""
     attribute_value: str
+    """The incompatible attribute value"""
     allowed_versions: List[AutosarVersion]
+    """list of versions in which the attribute value is permitted on this attribute"""
 
 class IncompatibleElementError:
+    """
+    Information about an element that is incompatible with a given target version
+    """
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
     element: Element
+    """incompatible element"""
     allowed_versions: List[AutosarVersion]
+    """list of versions in which this element is compatible"""
 
 class ValidSubElementInfo:
+    """
+    Details about a particular sub element
+    """
     element_name: str
+    """name of the potential sub element"""
     is_named: bool
+    """is the sub element named, i.e. does it need to be created with create_named_sub_element"""
     is_allowed: bool
+    """is the sub element currently allowed, given the existing content of the element. Note that some sub elements are mutually exclusive"""
 
-version: str
+__version__: str
+"""
+Version of the running autosar_data module.
+It contains a semver string of the form 'x.y.z'
+"""