Virtual methods and reduntant XmlDoc
-
Hi, I was wondering if anyone knows if there is a way of avoiding duplication of documentation when using virtual methods and polymorphy. If we use virtual methods properly they are overridden to do something in a different way, not to do something else, in a logical sense. Hence, the doc for an override should be the same as for the method it overrides. Is there any way to avoid having to copy the doc to all the base classes? Obviously the doc should be pretty stable in a perfect world, but then again the world is often imperfect and it's a pain to maintain consistency this way... [edit] Btw, I apologize if the C# forum isn't the approriate one for my question. XmlDoc is a C# feature, even if VB.NET and maybe other CLS-compliant languages provide something similar nowadays, so I didn't know where else it might go. Please say so if you feel there's another forum that would be more appropriate. [/edit]
-
Hi, I was wondering if anyone knows if there is a way of avoiding duplication of documentation when using virtual methods and polymorphy. If we use virtual methods properly they are overridden to do something in a different way, not to do something else, in a logical sense. Hence, the doc for an override should be the same as for the method it overrides. Is there any way to avoid having to copy the doc to all the base classes? Obviously the doc should be pretty stable in a perfect world, but then again the world is often imperfect and it's a pain to maintain consistency this way... [edit] Btw, I apologize if the C# forum isn't the approriate one for my question. XmlDoc is a C# feature, even if VB.NET and maybe other CLS-compliant languages provide something similar nowadays, so I didn't know where else it might go. Please say so if you feel there's another forum that would be more appropriate. [/edit]
In situations like that, I typically use the
includetag like so:<include file="xmldoc_common.xml" path="//method[@class='BaseClassName' and name='VirtualMethodName']/*" />
and the file will look like:
<xmldoc>
<method class="BaseClassName" name="VirtualMethodName">
<summary>The method does such and so.</summary>
<returns>A value depending on what happened</returns>
<exception cref="ArgumentNullException"><paramref name="paramA" />
is null.</exception>
</method>
</xmldoc>This lets you share as many or as few tags as you want. If you want to have separate remarks for each, just leave the remarks out of the common and put them on each derived class that needs them. If you need some common remarks and some class-specific remarks, well I haven't really worked that out. I think I tried it once and ended up with two remarks sections in the Sandcastle output. Only the summary, returns, exception, etc must match what is in the normal XML comments, all other tag names are whatever you want. The external xml file goes in the project (not solution) root.
-
In situations like that, I typically use the
includetag like so:<include file="xmldoc_common.xml" path="//method[@class='BaseClassName' and name='VirtualMethodName']/*" />
and the file will look like:
<xmldoc>
<method class="BaseClassName" name="VirtualMethodName">
<summary>The method does such and so.</summary>
<returns>A value depending on what happened</returns>
<exception cref="ArgumentNullException"><paramref name="paramA" />
is null.</exception>
</method>
</xmldoc>This lets you share as many or as few tags as you want. If you want to have separate remarks for each, just leave the remarks out of the common and put them on each derived class that needs them. If you need some common remarks and some class-specific remarks, well I haven't really worked that out. I think I tried it once and ended up with two remarks sections in the Sandcastle output. Only the summary, returns, exception, etc must match what is in the normal XML comments, all other tag names are whatever you want. The external xml file goes in the project (not solution) root.
Brilliant, thanks a lot!