[Add] Element query extension methods for annotating comments and a documentation summary; refs #511

[samatstariongroup]

Refs #511 (group 3 of 3: Package and Element)

Changes

New extension methods in uml4net.Extensions:

• IElement.QueryAnnotatingComments(): the owned comments of the element, followed by the comments of its direct and indirect owners that have the element as annotated element (Comment::annotatedElement), nearest owner first.
• IElement.QuerySummary(int maxLength = 160): the first sentence of QueryRawDocumentation, cut at the maximum length with an ellipsis when it is longer.

New Handlebars helpers in uml4net.HandleBars:

• Element.QueryAnnotatingComments, with the element as argument
• DocumentationSummary, with the element and optionally the maximum length as arguments

QueryDocumentation and QueryRawDocumentation are not changed: they read the owned comments only.

Where the methods come from

uml4net	Source	Difference with the source
QueryAnnotatingComments	EORSADB (QueryAllElementComments)	Rewritten. The source looks in the nearest package only and compares the identifier of the element with the unresolved reference identifiers of the comment. This method looks at every owner and uses the resolved Comment::annotatedElement.
QuerySummary	mycelium-hypha	Reads QueryRawDocumentation, where the source joins the lines of QueryDocumentation and collapses the white space. Throws for a maximum length below 1.

Rejected, as recorded in #511: QueryContainedAndImported of SysML2.NET (QueryAllNestedAndImportedPackages covers it), QueryAllElementCommentsIncludingEA of EORSADB (the Enterprise Architect reader adds that documentation as owned comments) and QueryDocumentationText of mycelium-hypha (QueryRawDocumentation covers it).

A limit of QueryAnnotatingComments

A comment that annotates the element and that is owned by an element which is not one of its owners, for example a package next to the package of the element, is not returned. Finding those needs a search through the whole model for each element. The documentation comment of the method states this.

Tests

• ElementExtensionsTestFixture: two tests, on elements built in the test, including the null argument and a maximum length of 0.
• DocumentationHelperTestFixture: one test for each new helper, including a wrong argument and a wrong number of arguments.
• Full suite: all 1,164 tests pass on this branch.

Not in this pull request

• The entries for the two helpers on the wiki page UML Handlebars Helpers, to be added when this is released.
• Group 1 (Class, [Add] Class and Classifier query extension methods and their Handlebars helpers; refs #511 #515) and group 2 (Property and Operation, [Add] Property query extension methods and their Handlebars helpers; refs #511 #516) of [Feature]: Move general UML query extension methods from SysML2.NET, EORSADB and mycelium into uml4net.Extensions #511. This branch is independent of both.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud