Xml documentation


DevX Home    Today's Headlines   Articles Archive   Tip Bank   Forums   

Results 1 to 8 of 8

Thread: Xml documentation

  1. #1
    Jeff Pipes Guest

    Xml documentation


    Out of curiosity, is anyone formatting or organizing their comments in preparation
    for when ms adds xml documentation to vb? I'm starting to think that I should
    be organizing my comments into sections that match the xml doc tags. For
    example-

    Public Function AddTwoNumbers(a as int16, b as int16) As Int16
    'Summary: Adds two numbers together and returns the result
    'Param Name: a
    'Param Description: The first number to add
    'Param Name: b
    'Param Description: The second number to add
    'Returns: The sum of a and b
    'Example: Debug.WriteLine(AddTwoNumber(1, 1)) 'returns 2

    Return a + b

    End Function

    Although this isn't xml, the sections names do match the xml tags so it should
    be fairly easy to convert this when vb.net 2.0 comes out. I'm just curious,
    is anyone else doing anything like this?

  2. #2
    Rob Teixeira Guest

    Re: Xml documentation



    Well, I've posted several times how much I really don't like adding all that
    stuff to the code. Download a C# sample that is well-documented using XML
    doc, and 3/4 of the class file (which is now hundreds of lines bigger than
    it was) is comments. I find it to be a lot of clutter, and makes it more
    difficult for me to look at the code. That's just personal opinion of course.
    But, if you do want to work with this in VB, you can download a sample add-in
    from the microsoft that adds the comment stubs and creates the XML HTML documentation
    based on the comments. It works for C#, VB.NET, and C++ projects.

    http://msdn.microsoft.com/vstudio/do...automation.asp

    Note that I found this sample to be particularly buggy in some cases. I had
    to make changes to the add-in source code to make it work.
    But it's a good learning experience at any rate.

    -Rob

    "Jeff Pipes" <JeffP622@msn.com> wrote:
    >
    >Out of curiosity, is anyone formatting or organizing their comments in preparation
    >for when ms adds xml documentation to vb? I'm starting to think that I should
    >be organizing my comments into sections that match the xml doc tags. For
    >example-
    >
    >Public Function AddTwoNumbers(a as int16, b as int16) As Int16
    >'Summary: Adds two numbers together and returns the result
    >'Param Name: a
    >'Param Description: The first number to add
    >'Param Name: b
    >'Param Description: The second number to add
    >'Returns: The sum of a and b
    >'Example: Debug.WriteLine(AddTwoNumber(1, 1)) 'returns 2
    >
    > Return a + b
    >
    >End Function
    >
    >Although this isn't xml, the sections names do match the xml tags so it

    should
    >be fairly easy to convert this when vb.net 2.0 comes out. I'm just curious,
    >is anyone else doing anything like this?



  3. #3
    Tim Overbay Guest

    Re: Xml documentation

    I fully documented my first C# program and, like Rob, found it kind of
    annoying to slog through all the documentation to get at the code. I hope
    that MSFT adds an option to show/hide doc code in the next version of VS.

    Tim

    "Rob Teixeira" <RobTeixeira@@msn.com> wrote in message
    news:3ce5221d$1@10.1.10.29...
    >
    >
    > Well, I've posted several times how much I really don't like adding all

    that
    > stuff to the code. Download a C# sample that is well-documented using XML
    > doc, and 3/4 of the class file (which is now hundreds of lines bigger than
    > it was) is comments. I find it to be a lot of clutter, and makes it more
    > difficult for me to look at the code. That's just personal opinion of

    course.
    > But, if you do want to work with this in VB, you can download a sample

    add-in
    > from the microsoft that adds the comment stubs and creates the XML HTML

    documentation
    > based on the comments. It works for C#, VB.NET, and C++ projects.
    >
    > http://msdn.microsoft.com/vstudio/do...automation.asp
    >
    > Note that I found this sample to be particularly buggy in some cases. I

    had
    > to make changes to the add-in source code to make it work.
    > But it's a good learning experience at any rate.
    >
    > -Rob
    >
    > "Jeff Pipes" <JeffP622@msn.com> wrote:
    > >
    > >Out of curiosity, is anyone formatting or organizing their comments in

    preparation
    > >for when ms adds xml documentation to vb? I'm starting to think that I

    should
    > >be organizing my comments into sections that match the xml doc tags. For
    > >example-
    > >
    > >Public Function AddTwoNumbers(a as int16, b as int16) As Int16
    > >'Summary: Adds two numbers together and returns the result
    > >'Param Name: a
    > >'Param Description: The first number to add
    > >'Param Name: b
    > >'Param Description: The second number to add
    > >'Returns: The sum of a and b
    > >'Example: Debug.WriteLine(AddTwoNumber(1, 1)) 'returns 2
    > >
    > > Return a + b
    > >
    > >End Function
    > >
    > >Although this isn't xml, the sections names do match the xml tags so it

    > should
    > >be fairly easy to convert this when vb.net 2.0 comes out. I'm just

    curious,
    > >is anyone else doing anything like this?

    >




  4. #4
    Tim Hitchings \(Infragistics\) Guest

    Re: Xml documentation

    Could you use regions?
    <http://msdn.microsoft.com/library/de...-us/vsintro7/h
    tml/vxtskOutliningCode.asp>

    "Tim Overbay" <luhar@neverendingsoftware.com> wrote in message
    news:3ce90933@10.1.10.29...
    > I fully documented my first C# program and, like Rob, found it kind of
    > annoying to slog through all the documentation to get at the code. I hope
    > that MSFT adds an option to show/hide doc code in the next version of VS.
    >
    > Tim
    >
    > "Rob Teixeira" <RobTeixeira@@msn.com> wrote in message
    > news:3ce5221d$1@10.1.10.29...
    > >
    > >
    > > Well, I've posted several times how much I really don't like adding all

    > that
    > > stuff to the code. Download a C# sample that is well-documented using

    XML
    > > doc, and 3/4 of the class file (which is now hundreds of lines bigger

    than
    > > it was) is comments. I find it to be a lot of clutter, and makes it more
    > > difficult for me to look at the code. That's just personal opinion of

    > course.
    > > But, if you do want to work with this in VB, you can download a sample

    > add-in
    > > from the microsoft that adds the comment stubs and creates the XML HTML

    > documentation
    > > based on the comments. It works for C#, VB.NET, and C++ projects.
    > >
    > > http://msdn.microsoft.com/vstudio/do...automation.asp
    > >
    > > Note that I found this sample to be particularly buggy in some cases. I

    > had
    > > to make changes to the add-in source code to make it work.
    > > But it's a good learning experience at any rate.
    > >
    > > -Rob
    > >
    > > "Jeff Pipes" <JeffP622@msn.com> wrote:
    > > >
    > > >Out of curiosity, is anyone formatting or organizing their comments in

    > preparation
    > > >for when ms adds xml documentation to vb? I'm starting to think that I

    > should
    > > >be organizing my comments into sections that match the xml doc tags.

    For
    > > >example-
    > > >
    > > >Public Function AddTwoNumbers(a as int16, b as int16) As Int16
    > > >'Summary: Adds two numbers together and returns the result
    > > >'Param Name: a
    > > >'Param Description: The first number to add
    > > >'Param Name: b
    > > >'Param Description: The second number to add
    > > >'Returns: The sum of a and b
    > > >'Example: Debug.WriteLine(AddTwoNumber(1, 1)) 'returns 2
    > > >
    > > > Return a + b
    > > >
    > > >End Function
    > > >
    > > >Although this isn't xml, the sections names do match the xml tags so it

    > > should
    > > >be fairly easy to convert this when vb.net 2.0 comes out. I'm just

    > curious,
    > > >is anyone else doing anything like this?

    > >

    >
    >




  5. #5
    John Butler Guest

    Re: Xml documentation


    "Tim Hitchings (Infragistics)" <productmanager@infragistics.com> wrote in
    message news:3ce91c04$1@10.1.10.29...

    You can't use regions with classes, which is not good. You can outline
    sure...but it isn't half as obvious or intuitive...which is a shortcoming in
    my books. I've tried collapsing an outline and then putting a comment in to
    show what the outline contains but it is clunky...unless there is a way, and
    I've missed it (entirely possible).




  6. #6
    Tim Hitchings \(Infragistics\) Guest

    Re: Xml documentation

    John Butler poorly sniped my suggestion to him that he use regions.
    HE is stating that he is unable to use regions.

    Could it be a CS versus VB issue?

    "Kevin Moore" <Kevin@MooreSSI.com> wrote in message
    news:3cea78c1$1@10.1.10.29...
    >
    > Tim,
    >
    > I was just able to add a region to a class in .Net so I am curious why you
    > feel that you can't use regions with classes?
    >
    > Kevin
    >
    > "John Butler" <nospamjrbutler@btinternet.com> wrote:
    > >
    > >"Tim Hitchings (Infragistics)" <productmanager@infragistics.com> wrote in
    > >message news:3ce91c04$1@10.1.10.29...
    > >
    > >You can't use regions with classes, which is not good. You can outline
    > >sure...but it isn't half as obvious or intuitive...which is a shortcoming

    > in
    > >my books. I've tried collapsing an outline and then putting a comment in

    > to
    > >show what the outline contains but it is clunky...unless there is a way,

    > and
    > >I've missed it (entirely possible).
    > >
    > >
    > >

    >




  7. #7
    Kevin Moore Guest

    Re: Xml documentation


    Tim,

    I was just able to add a region to a class in .Net so I am curious why you
    feel that you can't use regions with classes?

    Kevin

    "John Butler" <nospamjrbutler@btinternet.com> wrote:
    >
    >"Tim Hitchings (Infragistics)" <productmanager@infragistics.com> wrote in
    >message news:3ce91c04$1@10.1.10.29...
    >
    >You can't use regions with classes, which is not good. You can outline
    >sure...but it isn't half as obvious or intuitive...which is a shortcoming

    in
    >my books. I've tried collapsing an outline and then putting a comment in

    to
    >show what the outline contains but it is clunky...unless there is a way,

    and
    >I've missed it (entirely possible).
    >
    >
    >



  8. #8
    John Butler Guest

    Re: Xml documentation


    "Tim Hitchings (Infragistics)" <productmanager@infragistics.com> wrote in
    message news:3cea7c8b$1@10.1.10.29...
    > John Butler poorly sniped my suggestion to him that he use regions.
    > HE is stating that he is unable to use regions.
    >
    > Could it be a CS versus VB issue?
    >

    Apologies for that bad snipping...

    Also...I tried it again now..and it worked fine (don't know how or why I had
    problems the first time)..

    So...no, ignore my erroneous post. Regions are good, in VB as well as C#

    Rgds
    John Butler




Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
HTML5 Development Center
 
 
FAQ
Latest Articles
Java
.NET
XML
Database
Enterprise
Questions? Contact us.
C++
Web Development
Wireless
Latest Tips
Open Source


   Development Centers

   -- Android Development Center
   -- Cloud Development Project Center
   -- HTML5 Development Center
   -- Windows Mobile Development Center