`raesl.compile.ast.comment_storage`#

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#

`DocAddElement`	Interface class of an element that can store doc comments.
`DocElement`	Interface class of an element that can store and retrieve doc comments.
`DefaultDocElement`	Default implementation for storing and retrieving doc comments.
`DocStore`	Interface class that can find where to store doc comments for a given name.
`DefaultDocStore`	Class that can store and retrieve doc-comments for non-dotted names.
`ProxyDocStore`	Proxy element that represents a real DocStore element except at a different
`DummyElement`	Class for catching documentation elements that have no proper owner. Used for
`DocCommentDistributor`	Class for assigning documentation comments to relevant elements in the

Functions#

`decode_doc_comments`(→ List[str])	Convert a doc comment token to the containing description text.
`_drop_dup_dummies`(→ Generator[DocStore, None, None])	Drop dummy elements at the same offset as a non-dummy element.
`_gen_none`(→ Generator[None, None, None])	Generate a stream consisting of a single 'None' value.

class raesl.compile.ast.comment_storage.DocAddElement#

Interface class of an element that can store doc comments.

abstract add_comment(comment_tok: raesl.compile.scanner.Token) → None#

Add found documentation comment.

Parameters:: comment_tok – The raw documentation token to add.

class raesl.compile.ast.comment_storage.DocElement#

Bases: DocAddElement

Interface class of an element that can store and retrieve doc comments.

abstract get_comment() → List[str]#: Retrieve the stored comments.

class raesl.compile.ast.comment_storage.DefaultDocElement#

Bases: DocElement

Default implementation for storing and retrieving doc comments.

Parameters:: comments – The comments themselves, non-empty text after dropping the leading ‘#<’ and surrounding white-space.

add_comment(comment_tok: raesl.compile.scanner.Token)#

Add found documentation comment.

Parameters:: comment_tok – The raw documentation token to add.

get_comment() → List[str]#: Retrieve the stored comments.

raesl.compile.ast.comment_storage.decode_doc_comments(comment_tok: raesl.compile.scanner.Token) → List[str]#

Convert a doc comment token to the containing description text.

Parameters:: comment_tok – Token with the documentation comment.
Returns:: The text (for as far as it exists).

class raesl.compile.ast.comment_storage.DocStore(doc_tok: raesl.compile.scanner.Token | None)#

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.

Parameters:: 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.

abstract resolve_element(name: str) → DocAddElement | None#

Try to find the documentation element indicated by its (dotted) name.

Parameters:

name – Name of the element to find.

Returns:

The documentation element associated with the provided name if it can be: resolved.

get_error_position(name: str) → int#

Return the index in the given string where an error occurs in resolving the name.

Parameters:

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.

class raesl.compile.ast.comment_storage.DefaultDocStore(doc_tok: raesl.compile.scanner.Token | None)#

Bases: DocStore, DefaultDocElement

Class that can store and retrieve doc-comments for non-dotted names.

Parameters:: 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.

resolve_element(name: str)#

Try to find the documentation element indicated by its (dotted) name.

Parameters:

name – Name of the element to find.

Returns:

The documentation element associated with the provided name if it can be: resolved.

get_error_position(name: str)#

Return the index in the given string where an error occurs in resolving the name.

Parameters:

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.

class raesl.compile.ast.comment_storage.ProxyDocStore(doc_tok: raesl.compile.scanner.Token, real_element: DocStore)#

Bases: 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.

Parameters:

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.
real_element – Real element which is symbolically at the ‘doc_tok’ position, too.

resolve_element(name: str)#

Try to find the documentation element indicated by its (dotted) name.

Parameters:

name – Name of the element to find.

Returns:

The documentation element associated with the provided name if it can be: resolved.

get_error_position(name: str)#

Return the index in the given string where an error occurs in resolving the name.

Parameters:

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.

class raesl.compile.ast.comment_storage.DummyElement(doc_tok: raesl.compile.scanner.Token, report_errors: bool = True)#

Bases: DocStore, DocElement

Class for catching documentation elements that have no proper owner. Used for reporting warnings that such documentation is ignored.

Parameters:

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.
report_errors – Whether to add errors to the problem storage.

resolve_element(name: str)#

Try to find the documentation element indicated by its (dotted) name.

Parameters:

name – Name of the element to find.

Returns:

The documentation element associated with the provided name if it can be: resolved.

get_error_position(name: str)#

Return the index in the given string where an error occurs in resolving the name.

Parameters:

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.

add_comment(comment_tok: raesl.compile.scanner.Token)#

Add found documentation comment.

Parameters:: comment_tok – The raw documentation token to add.

get_comment()#: Retrieve the stored comments.

report(diag_store: raesl.compile.diagnostics.DiagnosticStore)#

Report a warning about all received documentation comments.

Parameters:: diag_store – Storage for reported diagnostics.

class raesl.compile.ast.comment_storage.DocCommentDistributor(diag_store: raesl.compile.diagnostics.DiagnosticStore)#

Class for assigning documentation comments to relevant elements in the specification.

Parameters:: diag_store – Storage for reported diagnostics.

elements#: Elements interested in receiving documentation comments.

dummy_elements#: Elements that catch documentation comments without a proper home, for warning the user about such comments.

add_dummy_element(doc_tok: raesl.compile.scanner.Token, report_errors: bool = True)#

Insert a dummy element based on the provided token.

Parameters:

doc_tok – Token that defines the position of the dummy element.
report_errors – Whether to report errors for comments that get attached to the dummy element.

add_element(element: DocStore)#

Add the provided element to the elements interested in getting doc comments.

Parameters:: element – Element to add.

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.

Parameters:: doc_comments – Documentation comments found in the input specification.

raesl.compile.ast.comment_storage._drop_dup_dummies(gen: List[DocStore]) → Generator[DocStore, None, None]#: Drop dummy elements at the same offset as a non-dummy element.

raesl.compile.ast.comment_storage._gen_none() → Generator[None, None, None]#: Generate a stream consisting of a single ‘None’ value.

raesl.compile.ast.comment_storage#

Module Contents#

Classes#

Functions#

`raesl.compile.ast.comment_storage`#