Tech Off Thread

14 posts

Forum Read Only

This forum has been made read only by the site admins. No new threads or comments can be added.

XML Documentation guidelines

Back to Forum: Tech Off
  • User profile image
    TommyCarlier

    Does anyone know of guidelines for writing XML documentation? What I need are some guidelines that explain what terminology to use to describe classes, properties, methods, events, ...

  • User profile image
    Tyler Brown

    XML documentation, as in the entire documentation for a project is encapsulated in XML?

  • User profile image
    Sven Groot

    Tyler Brown wrote:
    XML documentation, as in the entire documentation for a project is encapsulated in XML?

    I think he means XML comments like the ones used in C#.

  • User profile image
    Tyler Brown

    What exactly are the XML comments used for in C#? Do they allow some automated tool to create documentation for the release of an API?

  • User profile image
    blowdart

    Tyler Brown wrote:
    What exactly are the XML comments used for in C#? Do they allow some automated tool to create documentation for the release of an API?


    VS can do it for you, and it generates a set of web pages, but it really comes into it's own with ndoc

    ndoc will take your xml documentation output and produce CHM, HTML Help and MSDN style HTML for you. So you can publish your API on the web and merge it into VS's help via an MSI or H2Reg

  • User profile image
    TommyCarlier

    Yes, I actually mean the XML documentation that you embed in comments in C# code. I'd like to know if there are any guidelines for writing this kind of documentation.

  • User profile image
    blowdart

    TommyCarlier wrote:
    Yes, I actually mean the XML documentation that you embed in comments in C# code. I'd like to know if there are any guidelines for writing this kind of documentation.


    I tend to write mine in the style of the MSDN docs, so if I do fire out a class library it fits in nicely. Then as part of the installer I'll registered the HTML help that ndoc provides, so it's available in Visual Studio.

    One thing everyone seems to forget is the <exception /> tag. I've had to bash people about that one Smiley

  • User profile image
    zhuo

    Some sample would be nice Big Smile

    James

  • User profile image
    blowdart

    zhuo wrote:

    Some sample would be nice Big Smile

    James



    Of what? Type /// and there you go. If you really want a sample I'll try to dig out the last properly documented library I did, and paste a sample in

  • User profile image
    TommyCarlier

    blowdart wrote:
    TommyCarlier wrote: Yes, I actually mean the XML documentation that you embed in comments in C# code. I'd like to know if there are any guidelines for writing this kind of documentation.


    I tend to write mine in the style of the MSDN docs, so if I do fire out a class library it fits in nicely. Then as part of the installer I'll registered the HTML help that ndoc provides, so it's available in Visual Studio.

    One thing everyone seems to forget is the <exception /> tag. I've had to bash people about that one Smiley

    Yeah, that's what I want to do: make my documentation look like the MSDN documentation. But I guess I'll have to examine the docs and write some guidelines myself, if someone hasn't done it before.

  • User profile image
    blowdart

    TommyCarlier wrote:

    Yeah, that's what I want to do: make my documentation look like the MSDN documentation. But I guess I'll have to examine the docs and write some guidelines myself, if someone hasn't done it before.


    It's a style thing really. Make sure you use every option /// reveals.

    Then use ndoc to create MSDN HTML files, and if you're really fancy set the help up inside VS.

  • User profile image
    TommyCarlier

    blowdart wrote:
    TommyCarlier wrote:
    Yeah, that's what I want to do: make my documentation look like the MSDN documentation. But I guess I'll have to examine the docs and write some guidelines myself, if someone hasn't done it before.

    It's a style thing really. Make sure you use every option /// reveals.

    Then use ndoc to create MSDN HTML files, and if you're really fancy set the help up inside VS.

    I use every option /// reveals, that's not the problem. I want to know what kind of language to use.
    Examples:
    • Description of an event: Occurs when ...
    • Description of a get/set property: Gets or sets the ...
    • Description of a method that returns a bool: Indicates whether ...

  • User profile image
    Charles

    Why don't you just mimic what the BCL does? So, read the descriptions for the Framework's built-in Events, Methods, Classes, etc in the VS IDE (Intellisense...).

    That should give you a really good idea since the BCL follows the Official Managed Library Design Guidelines.

    C

  • User profile image
    TommyCarlier

    Charles wrote:
    Why don't you just mimic what the BCL does? So, read the descriptions for the Framework's built-in Events, Methods, Classes, etc in the VS IDE (Intellisense...).

    That should give you a really good idea since the BCL follows the Official Managed Library Design Guidelines.

    C

    That's indeed what I'm doing right now. When I need to document a method or an event or a property, I check the documentation of existing BCL classes, and write in a similar style.
    But I thought there might be some official guidelines that I could download that document how to document. Like there are guidelines that document how to write class libraries, how to design an API.

Conversation locked

This conversation has been locked by the site admins. No new comments can be made.