More VS Integration about nocco HOT 12 CLOSED

Honestly, I think that I've been avoiding the issue because I didn't want to answer that question. But, the more that I think about it, I think that Nocco needs to account for them in some way. Either comments starting with /// should be omitted or they should be formatted nicely in some way. If they are not omitted, I would like to come up with a different way of formatting them. In my mind, the typical API-style documentation doesn't belong with literate-style comments.

I've thought about 'hiding' them by default until you click or hover over something and they could then either appear inline in the documentation or in a popup. I'm not sure. But I think that you're right; they should be accounted for in some way.

from nocco.

For what it's worth, I agree that these formal intellisense/api spec documentation have no place in literate-style annotations.

There are already tools out there for generating api documentation from intellisense documentation.

from nocco.

You can't just run it through markdown, either. The parser would have to be smart enough to tease out <summary>, <remark>, while ignoring <param> etc

from nocco.

Ya, I'm thinking that those comments should probably just be ignored. But since they do exist in a lot of people's code, we should probably just explicitly ignore them. That way, someone can use Nocco and some other API documentation without any ugly XML appearing in their Nocco documentation.

from nocco.

Personally, I'd favour the <summary> and maybe event the <remark>s fields being output alongside the start of the function's definition in the documentation. Most people comment the start of their functions with an overview of what it does and it seems redundant to have them document it twice (once with standard comments // and then using the VS commenting system) in order so they can generate both literate-style and API-style documentation (the latter with a different tool, as you mentioned).
True, it is not going to be a straight-forward change to implement, but I think worthwhile.

from nocco.

After @EddPorter's last comment I began to see his point of view. Even though I dislike xml comments, handling it probably something the app should do. Using regular expressions, this didn't create too much code.

I added this functionality to my fork, but it doesn't apply to nocco without changes because it uses some regular expression extensions that I also made. See this section (or this commit) brandonc/curtsy@4137f8b

from nocco.

Ya, that makes more sense.

Still, I'm wondering if it makes complete sense. Visual studio and other API generators will use that description and if you put markdown in there, it obviously won't get parsed as markdown. So, it still seems possible that you might want to keep nocco documentation separate. You might also want a more concise description that appears in your Intellisense and more complete
description in the nocco documentation. What do you think?

from nocco.

I think recommending duplicating the comments in source is a mistake because oftentimes the <summary> is exactly what you would provide as nocco-style documentation anyway. Even if a 'more complete' description appeared outside xml comments, there would inevitably be a lot of redundancy! I think developers would choose either annotation style, markdown decorated comments or those formal, unformatted visual studio xml comments.

Practical example:

This source file has a lot of xml documentation in it, and here is the interpretation of it.

Running those xml comments through markdown usually has no effect on it (aside from paragraphing it), which is fine. Formatting is optional.

from nocco.

Good point. I agree. Thanks for collaborating with me on this idea, btw.

So, I have one more question. You can do some interesting things with XML inside the <summary> and the <remarks> tags. For example (source):

/// <summary>
///   The <c>DocumentationSample</c> type demonstrates code comments.
/// </summary>
/// <remarks>
///   <para>
///     The <c>DocumentationSample</c> type provides no real functionality; 
///     however, it does provide examples of using the most common, built-in 
///     <c>C#</c> xml documentation tags.
///   </para>
///   <para>
///     <c>DocumentationSample</c> types are not safe for concurrent access by 
///     multiple threads.
///   </para>
/// </remarks>

If we are going to intentionally include the comments inside summary and remarks, should we do something with the XML inside there as well? (For quick reference, here is a list of all the tags that Visual Studio 2010 supports and several of them can occur within the summary or remarks tags).

from nocco.

This revelation has opened a nasty can of worms. This is essentially a hard-to-translate pseudo html. Consider these two examples!

Roughly equivalent to ul/li:

/// <list type="bullet">
///     <item>
///         <description>Item 1.</description>
///     </item>
///     <item>
///         <description>Item 2.</description>
///     </item>
/// </list>

Roughly equivalent to table

/// <list type="table">
///     <listheader>
///         <term>term</term>
///         <description>description</description>
///     </listheader>
///     <item>
///         <term>term</term>
///         <description>description</description>
///     </item>
/// </list>

BUT. Markup is passed through markdown unchanged. For your example, my md parser renders:

<p>The <c>DocumentationSample</c> type demonstrates code comments.</p>

<p><para>
    The <c>DocumentationSample</c> type provides no real functionality;
    however, it does provide examples of using the most common, built-in
    <c>C#</c> xml documentation tags.
</para>
<para>
    <c>DocumentationSample</c> types are not safe for concurrent access by
    multiple threads.
</para></p>

Which all browsers should render without problem.

A partial solution would be to replace <c> and <para> to the html or markdown equivalent:

<c> becomes `

<para> becomes <p>

WHY DID THEY INVENT THEIR OWN HTML?

from nocco.

For what it's worth, it would be neat if Nocco did this, but I was looking at it more to document files that typically don't have a tool to do it nicely (read: beautiful) like .coffee, .js, and .css files. I've used SandCastle to generate .NET API documentation and it works for the most part despite not being as "pretty."

VS seems to enforce XML semantics in the documentation, so it's really XML, not pseudo-HTML. If you think of it like that, you could write a fairly short LINQ to XML converter, but I am not sure to what extent you can change tags or perhaps even replace with Markdown syntax using L2XML.

from nocco.

Pull request #7 adds support for the most commonly used XML documentation comments. It also provides a suggested way for more to be added in the future.

from nocco.