I have comments like this:
/// <summary>some summary</summary>
/// <param name="a">
/// <para id="0">Comment 0</para>
/// <para id="1">Comment 1</para>
/// <para id="2">Comment 2</para>
/// </param>
/// <param name="b">
/// <para id="1">Comment 3</para>
/// <para id="0">Comment 4</para>
/// </param>
void InterfaceMethod(int a, int b);
For the implementing method, I'd like to have the same documentation, but without those paragraphs having id="0"
, using inheritdoc
.
How can I author the inheritdoc
element?
The uncommon use of the id
attributes in this context shall add the flexibility of not being tied to the order of the paragraphs as they appear in the documentation.
I found a solution, but it looks cumbersome.
/// <summary><inheritdoc/></summary>
/// <param name="a"><inheritdoc select="node()[parent::node()[@name='a'] and @id>0]"/></param>
/// <param name="b"><inheritdoc select="node()[parent::node()[@name='b'] and @id>0]"/></param>
public void InterfaceMethod(int a, int b) { }
As it is not possible to use XPath expressions as a filter, the param
elements must be repeated.
The expression @id>0
(the >
needed to be escaped) now selects the intended paragraphs only.
But what about the other markup?
The nested inheritdoc
element will select the content of all param
nodes, so we must add a condition on the parent's name attribute.
Finally, the inheritdoc
tag within the summary
tag will copy the summary. If we placed a inheritdoc
on root level, this would again select the param
, as described here.