:py:mod:`raesl.compile.ast.comment_storage` =========================================== .. py:module:: raesl.compile.ast.comment_storage .. autoapi-nested-parse:: Code for handling documentation comments in AST objects. The code has two main concepts, namely DocStore which expresses the capability to find elements that can store doc comments, and DocAddElement which expresses the capability to actually store such comments. In general thus, storing a doc comment thus involves two steps. First the correct element is searched based on a supplied (possibly dotted) name, then the comment is actually stored if an element could be found. As the above is pretty minimal, several additional classes exist. - The DocElement can both store comments and also provide them again. (Compound element can't store comments, but forward them to their children and thus have no way to retrieve the comments given to them.) - The DefaultDocElement implements DocElement. - The DefaultDocStore implements a DocStore as well as DocElement for non-dotted names, providing a simple way to add doc comment storage to many of the language elements. Internally, some more classes exist. - The ProxyDocStore that acts as DocStore elsewhere in the specification. Its primary use is in comment sections, pointing to the actual elements to receive the doc comments of the section. - The DummyElement acts as a DocStore for any doc comment, and reports a warning about them being ignored. These elements act as barrier and guard against doc comments being added to a previous element where that should not happen. For example, doc comments after a 'define type' line, should not be added to the definitions above that line. - Finally, DocCommentDistributor implements the distribution of doc comments to all elements of the specification after type-checking has been performed. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: raesl.compile.ast.comment_storage.DocAddElement raesl.compile.ast.comment_storage.DocElement raesl.compile.ast.comment_storage.DefaultDocElement raesl.compile.ast.comment_storage.DocStore raesl.compile.ast.comment_storage.DefaultDocStore raesl.compile.ast.comment_storage.ProxyDocStore raesl.compile.ast.comment_storage.DummyElement raesl.compile.ast.comment_storage.DocCommentDistributor Functions ~~~~~~~~~ .. autoapisummary:: raesl.compile.ast.comment_storage.decode_doc_comments raesl.compile.ast.comment_storage._drop_dup_dummies raesl.compile.ast.comment_storage._gen_none .. py:class:: DocAddElement Interface class of an element that can store doc comments. .. py:method:: add_comment(comment_tok: raesl.compile.scanner.Token) -> None :abstractmethod: Add found documentation comment. :param comment_tok: The raw documentation token to add. .. py:class:: DocElement Bases: :py:obj:`DocAddElement` Interface class of an element that can store and retrieve doc comments. .. py:method:: get_comment() -> List[str] :abstractmethod: Retrieve the stored comments. .. py:class:: DefaultDocElement Bases: :py:obj:`DocElement` Default implementation for storing and retrieving doc comments. :param comments: The comments themselves, non-empty text after dropping the leading '#<' and surrounding white-space. .. py:method:: add_comment(comment_tok: raesl.compile.scanner.Token) Add found documentation comment. :param comment_tok: The raw documentation token to add. .. py:method:: get_comment() -> List[str] Retrieve the stored comments. .. py:function:: decode_doc_comments(comment_tok: raesl.compile.scanner.Token) -> List[str] Convert a doc comment token to the containing description text. :param comment_tok: Token with the documentation comment. :returns: The text (for as far as it exists). .. py:class:: DocStore(doc_tok: Optional[raesl.compile.scanner.Token]) Interface class that can find where to store doc comments for a given name. If doc_tok is None, the element does not get any documentation comments. :param doc_tok: Token defining the position of the element in the input for documenting. Documentation comments after this position and before any other existing DocStore.doc_tok will be attached to this element. .. py:method:: resolve_element(name: str) -> Optional[DocAddElement] :abstractmethod: Try to find the documentation element indicated by its (dotted) name. :param name: Name of the element to find. :returns: The documentation element associated with the provided name if it can be resolved. .. py:method:: get_error_position(name: str) -> int Return the index in the given string where an error occurs in resolving the name. :param name: Name of the element to find. :returns: Approximated index in the string where matching the element fails. Returned value has no meaning if resolving succeeds. .. py:class:: DefaultDocStore(doc_tok: Optional[raesl.compile.scanner.Token]) Bases: :py:obj:`DocStore`, :py:obj:`DefaultDocElement` Class that can store and retrieve doc-comments for non-dotted names. :param doc_tok: Token defining the position of the element in the input for documenting. Documentation comments after this position and before any other existing DocStore.doc_tok will be attached to this element. .. py:method:: resolve_element(name: str) Try to find the documentation element indicated by its (dotted) name. :param name: Name of the element to find. :returns: The documentation element associated with the provided name if it can be resolved. .. py:method:: get_error_position(name: str) Return the index in the given string where an error occurs in resolving the name. :param name: Name of the element to find. :returns: Approximated index in the string where matching the element fails. Returned value has no meaning if resolving succeeds. .. py:class:: ProxyDocStore(doc_tok: raesl.compile.scanner.Token, real_element: DocStore) Bases: :py:obj:`DocStore` Proxy element that represents a real DocStore element except at a different position in the specification. This is useful in 'comment' sections where names of elements are provided that exist elsewhere in the component. :param doc_tok: Token defining the position of the element in the input for documenting. Documentation comments after this position and before any other existing DocStore.doc_tok will be attached to this element. :param real_element: Real element which is symbolically at the 'doc_tok' position, too. .. py:method:: resolve_element(name: str) Try to find the documentation element indicated by its (dotted) name. :param name: Name of the element to find. :returns: The documentation element associated with the provided name if it can be resolved. .. py:method:: get_error_position(name: str) Return the index in the given string where an error occurs in resolving the name. :param name: Name of the element to find. :returns: Approximated index in the string where matching the element fails. Returned value has no meaning if resolving succeeds. .. py:class:: DummyElement(doc_tok: raesl.compile.scanner.Token, report_errors: bool = True) Bases: :py:obj:`DocStore`, :py:obj:`DocElement` Class for catching documentation elements that have no proper owner. Used for reporting warnings that such documentation is ignored. :param doc_tok: Token defining the position of the element in the input for documenting. Documentation comments after this position and before any other existing DocStore.doc_tok will be attached to this element. :param report_errors: Whether to add errors to the problem storage. .. py:method:: resolve_element(name: str) Try to find the documentation element indicated by its (dotted) name. :param name: Name of the element to find. :returns: The documentation element associated with the provided name if it can be resolved. .. py:method:: get_error_position(name: str) Return the index in the given string where an error occurs in resolving the name. :param name: Name of the element to find. :returns: Approximated index in the string where matching the element fails. Returned value has no meaning if resolving succeeds. .. py:method:: add_comment(comment_tok: raesl.compile.scanner.Token) Add found documentation comment. :param comment_tok: The raw documentation token to add. .. py:method:: get_comment() Retrieve the stored comments. .. py:method:: report(diag_store: raesl.compile.diagnostics.DiagnosticStore) Report a warning about all received documentation comments. :param diag_store: Storage for reported diagnostics. .. py:class:: DocCommentDistributor(diag_store: raesl.compile.diagnostics.DiagnosticStore) Class for assigning documentation comments to relevant elements in the specification. :param diag_store: Storage for reported diagnostics. .. attribute:: elements Elements interested in receiving documentation comments. .. attribute:: dummy_elements Elements that catch documentation comments without a proper home, for warning the user about such comments. .. py:method:: add_dummy_element(doc_tok: raesl.compile.scanner.Token, report_errors: bool = True) Insert a dummy element based on the provided token. :param doc_tok: Token that defines the position of the dummy element. :param report_errors: Whether to report errors for comments that get attached to the dummy element. .. py:method:: add_element(element: DocStore) Add the provided element to the elements interested in getting doc comments. :param element: Element to add. .. py:method:: resolve(doc_comments: List[raesl.compile.scanner.Token]) Distribute the provided documentation comments to the interested elements, and report any documentation comments that get assigned in a DummyElement, as those are at the wrong spot in the specification. :param doc_comments: Documentation comments found in the input specification. .. py:function:: _drop_dup_dummies(gen: List[DocStore]) -> Generator[DocStore, None, None] Drop dummy elements at the same offset as a non-dummy element. .. py:function:: _gen_none() -> Generator[None, None, None] Generate a stream consisting of a single 'None' value.