Filter content of inherited param comments

Question

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.

score 0 · Accepted Answer · edited May 23 '17 at 12:21

I found a solution, but it looks cumbersome.

/// <summary><inheritdoc/></summary>
/// <param name="a"><inheritdoc select="node()[parent::node()[@name='a'] and @id&gt;0]"/></param>
/// <param name="b"><inheritdoc select="node()[parent::node()[@name='b'] and @id&gt;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.

Filter content of inherited param comments

1 Answers1