StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

PO
text
Body
copied!<p><em>I have a better answer: <strong>FiXml</strong>.</em> </p> <p>Cloning comments with GhostDoc is certainly working approach, but it has significant disadvantages, e.g.: </p> <ul> <li>When the original comment is changed (which frequently happens during development), its clone is not.</li> <li>You're producing huge amount of duplicates. If you're using any source code analysis tools (e.g. Duplicate Finder in Team City), it will find mainly your comments.</li> </ul> <p>Short description of FiXml: it is a post-processor of XML documentation produced by C# \ Visual Basic .Net. It is implemented as MSBuild task, so it's quite easy to integrate it to any project. It addresses few annoying cases related to writing XML documentation in these languages:</p> <ul> <li><strong>No support for inheriting the documentation from base class or interface.</strong> I.e. a documentation for any overridden member should be written from scratch, although normally it’s quite desirable to inherit at least the part of it.</li> <li><strong>No support for insertion of commonly used documentation templates</strong>, such as “This type is singleton - use its <code><see cref="Instance" /></code> property to get the only instance of it.”, or even “Initializes a new instance of <code><CurrentType></code> class.”</li> </ul> <p>To solve mentioned issues, the following additional XML tags are provided:</p> <ul> <li><code><inheritdoc />, <inherited /></code> tags</li> <li><code><see cref="..." copy="..." /></code> attribute in <code><see/></code> tag.</li> </ul> <p>Here is <a href="http://wiki.dataobjects.net/index.php?title=FiXml" rel="nofollow noreferrer">its web page</a> and <a href="http://www.x-tensive.com/Downloads/?Path=Freeware%5CXtensive.MSBuildTasks" rel="nofollow noreferrer">download page</a> (broken links).</p> <p><em>Finally, there is <code><inheritdoc></code> tag in <a href="https://github.com/EWSoftware/SHFB" rel="nofollow noreferrer">Sandcastle</a></em> - it's definitely better to use it than to copy XML comments, but it has few disadvantages in comparison to FiXml:</p> <ul> <li>Sandcastle produces compiled HTML help files - it doesn't modify <code>.xml</code> files containing extracted XML comments. But these files are used by many tools, including .NET Reflector and class browser \ IntelliSense in Visual Studio .NET. So if you use just Sandcastle, you won't see inherited documentation there.</li> <li>Sandcastle's implementation is less powerful. E.g. the is no <code><see ... copy="true" /></code>.</li> </ul> <p>See <a href="http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm" rel="nofollow noreferrer">Sandcastle's <code><inheritdoc></code> description</a> for further details.</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload