locked
XML Documentation Comments & Sandcastle comments RRS feed

  • Question

  • Is there (anywhere) a comprehensive list of tags that can be used in XML Document Comments and the attributes that go along with them, that are used/parsed/available for Sandcastle?

     

    I have seen the docs on XML Document Comments on MSDN (http://msdn2.microsoft.com/en-us/library/5ast78ax(VS.80).aspx) and looked at the NDoc documentation, and looked at the various sandcastle blog entries mentioned on various posts in this forum. 

     

    The tag usage for some tags is identical, whereas for other tags, the differ.  Even the stuff on MSDN is not the same... one example shows the <see> element as
        "<see cref="name"/>"
    while another shows it as
        "<see cref="name">description</see>"

     

    I have yet to find a comprehensive list of tag/attributes or (even better) an example doc that shows the tags/attributes and the various ways they can be used.

     

    Anyone know where I can find either a listing or an example of the tags/attributes that are available for XML Documentation Comments and for Sandcastle?

     

    Thanks,

    Eric

    Thursday, July 12, 2007 12:26 AM

Answers

All replies

  • I'm not aware of any comprehensive documentation for the XML comments tags for Sandcastle specifically.  The nDoc documentation is probably the closest you can get although Sandcastle doesn't support all of nDoc's tags nor does it support href attributes in place of cref attributes.  The <see> tag can be used both ways that you noted.  You can use the inner text version to alter the descriptive text used for the link.  That applies to <seealso> as well.

     

    Eric

     

    Thursday, July 12, 2007 2:00 AM
  • Eric,
        Thanks for the info.
     
    Eric
    Thursday, July 12, 2007 12:05 PM
  • Don't know the origin of it (I found it by chance with google) but this is quite a nice reference:

     

    http://p3net.mvps.org/downloads/docs/DocGuidelines.doc

     

    Cheers,

     

    Bill

     

    Thursday, July 12, 2007 1:22 PM
  • Bill,
        Thanks for the link!  I just took a quick look through the doc, and it looks very promising.  I don't know how I did not find it, I spent more hours than I care to think about on Google, MSN Search and MSDN looking for documentation, and all I found were pieces, or contradictory documentation.
     
    Thanks again,
     
    Eric
    Thursday, July 12, 2007 1:32 PM