473,320 Members | 2,146 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,320 software developers and data experts.

Some .NET XML documentation tags are not recognized when I update my solution's documentation

I have a Windows program C# .NET solution where when I update its XML
documentation, some tags are not recognized and turned into the
corresponding HTML. Those tags include <c>, <code>, <para>, <paramref>, and
<exception>. <remarks> works; I have not tried <include>. Is this a bug in
Studio or am I using those tags incorrectly?

When the tag appears to have an attribute, I have tried
<paramref="parameter">paramter name</paramref> and the way that autocomplete
completes the tag: <paramref=">parameter"/>. Since neither works, which is
correct? What, if anything, am I doing wrong?

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
Nov 16 '05 #1
8 1954
Will Pittenger wrote:
I have a Windows program C# .NET solution where when I update its XML
documentation, some tags are not recognized and turned into the
corresponding HTML. Those tags include <c>, <code>, <para>,
<paramref>, and <exception>. <remarks> works; I have not tried
<include>. Is this a bug in Studio or am I using those tags
incorrectly?

When the tag appears to have an attribute, I have tried
<paramref="parameter">paramter name</paramref> and the way that
autocomplete completes the tag: <paramref=">parameter"/>. Since
neither works, which is correct? What, if anything, am I doing wrong?


Other than using the wrong tool... nothing ;-)

It's sorry that this particular feature of VS .NET is rather useless,
because it just does not support all the tags (for whatever reason). Switch
to NDoc, which is free and vastly superior: http://ndoc.sourceforge.net/wiki

Cheers,

--
Joerg Jooss
jo*********@gmx.net
Nov 16 '05 #2
So, why doesn't Microsoft's documentation match what Microsoft actually
supports? Does this other package use the same tags and work from within
VS?

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Joerg Jooss" <jo*********@gmx.net> wrote in message
news:Om**************@TK2MSFTNGP11.phx.gbl...
Will Pittenger wrote:
I have a Windows program C# .NET solution where when I update its XML
documentation, some tags are not recognized and turned into the
corresponding HTML. Those tags include <c>, <code>, <para>,
<paramref>, and <exception>. <remarks> works; I have not tried
<include>. Is this a bug in Studio or am I using those tags
incorrectly?

When the tag appears to have an attribute, I have tried
<paramref="parameter">paramter name</paramref> and the way that
autocomplete completes the tag: <paramref=">parameter"/>. Since
neither works, which is correct? What, if anything, am I doing wrong?
Other than using the wrong tool... nothing ;-)

It's sorry that this particular feature of VS .NET is rather useless,
because it just does not support all the tags (for whatever reason).

Switch to NDoc, which is free and vastly superior: http://ndoc.sourceforge.net/wiki
Cheers,

--
Joerg Jooss
jo*********@gmx.net

Nov 16 '05 #3
NDoc iks not integrated with VS (to my knowledge) but it does support the
tags that Microsoft defined (<c>, <para>, <list> etc)

You can create an NDoc project file (*.ndoc), and then add that file to your
visual studio solution. If you then tell VS to associate that NDoc project
file with the NDoc executable, you can just double click the ndoc file in VS
and it will open NDoc for you. Hit the "build" button in ndoc and it will
build help for you - only one more step than what you currently are doing.

The resulting help files can be integrated with visual studio:
http://www.reflectionit.nl/NDoc.aspx

As for why MS doesn't support their own documentation, my guess is
resources. I suppose that they had big plans but didn't have the time to
make it all happen (but at least they got the important part of the xml
comments and defining set syntax). NDoc came along and made it happen, so
there isn't as much reason for MS to reinvent the wheel (not that they
haven't done that before).
--
Mike Mayer, C# MVP
mi**@mag37.com
http://www.mag37.com/csharp/

"Will Pittenger" <wi************@verizon.net> wrote in message
news:u2**************@tk2msftngp13.phx.gbl...
So, why doesn't Microsoft's documentation match what Microsoft actually
supports? Does this other package use the same tags and work from within
VS?

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Joerg Jooss" <jo*********@gmx.net> wrote in message
news:Om**************@TK2MSFTNGP11.phx.gbl...
Will Pittenger wrote:
I have a Windows program C# .NET solution where when I update its XML
documentation, some tags are not recognized and turned into the
corresponding HTML. Those tags include <c>, <code>, <para>,
<paramref>, and <exception>. <remarks> works; I have not tried
<include>. Is this a bug in Studio or am I using those tags
incorrectly?

When the tag appears to have an attribute, I have tried
<paramref="parameter">paramter name</paramref> and the way that
autocomplete completes the tag: <paramref=">parameter"/>. Since
neither works, which is correct? What, if anything, am I doing wrong?


Other than using the wrong tool... nothing ;-)

It's sorry that this particular feature of VS .NET is rather useless,
because it just does not support all the tags (for whatever reason).

Switch
to NDoc, which is free and vastly superior:

http://ndoc.sourceforge.net/wiki

Cheers,

--
Joerg Jooss
jo*********@gmx.net


Nov 16 '05 #4
Well, I have suspected for several years that Microsoft always has a
"super-duper" build system that they keep to themselves. Everything works
and is better thought out. They certainly put their favorite goodies into
their own products before making them available in MFC, Win32, or .NET. As
an example, notice that Office does not follow your XP skin (or WindowBlinds
skin for that matter). You can get the look offered by the toolbar buttons
for buttons, button-style checkboxes, and button-style radio buttons, but
not in the .NET or MFC toolbars. In order to get AutoComplete to see new
classes and/or new members of classes, I commonly have to restart VS.

Microsoft's not supporting those tags may be more of the same. They
probably even claim they are helping 3rd party add-in developers out.

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Michael Mayer [C# MVP]" <mi**@mag37.com> wrote in message
news:eR**************@TK2MSFTNGP10.phx.gbl...
NDoc iks not integrated with VS (to my knowledge) but it does support the
tags that Microsoft defined (<c>, <para>, <list> etc)

You can create an NDoc project file (*.ndoc), and then add that file to your visual studio solution. If you then tell VS to associate that NDoc project
file with the NDoc executable, you can just double click the ndoc file in VS and it will open NDoc for you. Hit the "build" button in ndoc and it will
build help for you - only one more step than what you currently are doing.

The resulting help files can be integrated with visual studio:
http://www.reflectionit.nl/NDoc.aspx

As for why MS doesn't support their own documentation, my guess is
resources. I suppose that they had big plans but didn't have the time to
make it all happen (but at least they got the important part of the xml
comments and defining set syntax). NDoc came along and made it happen, so
there isn't as much reason for MS to reinvent the wheel (not that they
haven't done that before).
--
Mike Mayer, C# MVP
mi**@mag37.com
http://www.mag37.com/csharp/

"Will Pittenger" <wi************@verizon.net> wrote in message
news:u2**************@tk2msftngp13.phx.gbl...
So, why doesn't Microsoft's documentation match what Microsoft actually
supports? Does this other package use the same tags and work from within VS?

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Joerg Jooss" <jo*********@gmx.net> wrote in message
news:Om**************@TK2MSFTNGP11.phx.gbl...
Will Pittenger wrote:
> I have a Windows program C# .NET solution where when I update its XML > documentation, some tags are not recognized and turned into the
> corresponding HTML. Those tags include <c>, <code>, <para>,
> <paramref>, and <exception>. <remarks> works; I have not tried
> <include>. Is this a bug in Studio or am I using those tags
> incorrectly?
>
> When the tag appears to have an attribute, I have tried
> <paramref="parameter">paramter name</paramref> and the way that
> autocomplete completes the tag: <paramref=">parameter"/>. Since
> neither works, which is correct? What, if anything, am I doing wrong?
Other than using the wrong tool... nothing ;-)

It's sorry that this particular feature of VS .NET is rather useless,
because it just does not support all the tags (for whatever reason).

Switch
to NDoc, which is free and vastly superior:

http://ndoc.sourceforge.net/wiki

Cheers,

--
Joerg Jooss
jo*********@gmx.net



Nov 16 '05 #5
I was just looking at NDoc's website. From what I can tell, I might have to
build their project to install it. Second, in order to see updated
documentation, you must be able to build with no errors. Third,
IntelliSense does not help with the NDoc extensions to the tags. Fourth,
some hand coding of XML is required. (I have never worked directly with
XML.)

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Michael Mayer [C# MVP]" <mi**@mag37.com> wrote in message
news:eR**************@TK2MSFTNGP10.phx.gbl...
NDoc iks not integrated with VS (to my knowledge) but it does support the
tags that Microsoft defined (<c>, <para>, <list> etc)

You can create an NDoc project file (*.ndoc), and then add that file to your visual studio solution. If you then tell VS to associate that NDoc project
file with the NDoc executable, you can just double click the ndoc file in VS and it will open NDoc for you. Hit the "build" button in ndoc and it will
build help for you - only one more step than what you currently are doing.

The resulting help files can be integrated with visual studio:
http://www.reflectionit.nl/NDoc.aspx

As for why MS doesn't support their own documentation, my guess is
resources. I suppose that they had big plans but didn't have the time to
make it all happen (but at least they got the important part of the xml
comments and defining set syntax). NDoc came along and made it happen, so
there isn't as much reason for MS to reinvent the wheel (not that they
haven't done that before).
--
Mike Mayer, C# MVP
mi**@mag37.com
http://www.mag37.com/csharp/

"Will Pittenger" <wi************@verizon.net> wrote in message
news:u2**************@tk2msftngp13.phx.gbl...
So, why doesn't Microsoft's documentation match what Microsoft actually
supports? Does this other package use the same tags and work from within VS?

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Joerg Jooss" <jo*********@gmx.net> wrote in message
news:Om**************@TK2MSFTNGP11.phx.gbl...
Will Pittenger wrote:
> I have a Windows program C# .NET solution where when I update its XML > documentation, some tags are not recognized and turned into the
> corresponding HTML. Those tags include <c>, <code>, <para>,
> <paramref>, and <exception>. <remarks> works; I have not tried
> <include>. Is this a bug in Studio or am I using those tags
> incorrectly?
>
> When the tag appears to have an attribute, I have tried
> <paramref="parameter">paramter name</paramref> and the way that
> autocomplete completes the tag: <paramref=">parameter"/>. Since
> neither works, which is correct? What, if anything, am I doing wrong?
Other than using the wrong tool... nothing ;-)

It's sorry that this particular feature of VS .NET is rather useless,
because it just does not support all the tags (for whatever reason).

Switch
to NDoc, which is free and vastly superior:

http://ndoc.sourceforge.net/wiki

Cheers,

--
Joerg Jooss
jo*********@gmx.net



Nov 16 '05 #6
Will Pittenger wrote:
I was just looking at NDoc's website. From what I can tell, I might
have to build their project to install it.
Come on, you're a developer ;-)
But there's no need to do that. Go to the project's page on SourceForge and
download a stable package (ndoc-devel-v1.2.zip):

http://sourceforge.net/project/showf...group_id=36057

If you want t create .chm help files, you will also need to install MS HTML
Workshop, which can be downloaded from MSDN or should be coming with your
version of VS .NET.
Second, in order to see
updated documentation, you must be able to build with no errors.
I'm not sure whether this an NDoc limitation -- the C# compiler produces all
necessary output for document generation.
Third, IntelliSense does not help with the NDoc extensions to the
tags.
Correct, but nothing forces you to use them.
Fourth, some hand coding of XML is required. (I have never
worked directly with XML.)


Well, you do work with C# XML comments already, don't you? Anyway, for basic
documentation generation, NDoc should work out-of-the-box if you stick to
the original comment tags you already know.

Cheers,

--
Joerg Jooss
jo*********@gmx.net

Nov 16 '05 #7
With Microsoft's documenter, you can update the documentation from the Tools
menu without building.

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Joerg Jooss" <jo*********@gmx.net> wrote in message
news:OY**************@tk2msftngp13.phx.gbl...
Will Pittenger wrote:
I was just looking at NDoc's website. From what I can tell, I might
have to build their project to install it.
Come on, you're a developer ;-)
But there's no need to do that. Go to the project's page on SourceForge

and download a stable package (ndoc-devel-v1.2.zip):

http://sourceforge.net/project/showf...group_id=36057

If you want t create .chm help files, you will also need to install MS HTML Workshop, which can be downloaded from MSDN or should be coming with your
version of VS .NET.
Second, in order to see
updated documentation, you must be able to build with no errors.
I'm not sure whether this an NDoc limitation -- the C# compiler produces

all necessary output for document generation.
Third, IntelliSense does not help with the NDoc extensions to the
tags.
Correct, but nothing forces you to use them.
Fourth, some hand coding of XML is required. (I have never
worked directly with XML.)


Well, you do work with C# XML comments already, don't you? Anyway, for

basic documentation generation, NDoc should work out-of-the-box if you stick to
the original comment tags you already know.

Cheers,

--
Joerg Jooss
jo*********@gmx.net

Nov 16 '05 #8
Have you posted projects with NDoc specific tags to CodeProject? While
other users might not have a problem with the compiled project, they may be
unable to build the help system. I did want to post my project when I am
done.

----------
Will Pittenger
E-Mail: mailto:wi************@verizon.net
All mail filtered by Qurb (www.qurb.com)
"Joerg Jooss" <jo*********@gmx.net> wrote in message
news:OY**************@tk2msftngp13.phx.gbl...
Will Pittenger wrote:
I was just looking at NDoc's website. From what I can tell, I might
have to build their project to install it.
Come on, you're a developer ;-)
But there's no need to do that. Go to the project's page on SourceForge

and download a stable package (ndoc-devel-v1.2.zip):

http://sourceforge.net/project/showf...group_id=36057

If you want t create .chm help files, you will also need to install MS HTML Workshop, which can be downloaded from MSDN or should be coming with your
version of VS .NET.
Second, in order to see
updated documentation, you must be able to build with no errors.
I'm not sure whether this an NDoc limitation -- the C# compiler produces

all necessary output for document generation.
Third, IntelliSense does not help with the NDoc extensions to the
tags.
Correct, but nothing forces you to use them.
Fourth, some hand coding of XML is required. (I have never
worked directly with XML.)


Well, you do work with C# XML comments already, don't you? Anyway, for

basic documentation generation, NDoc should work out-of-the-box if you stick to
the original comment tags you already know.

Cheers,

--
Joerg Jooss
jo*********@gmx.net

Nov 16 '05 #9

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

10
by: C Williams | last post by:
Hi, In a nutshell, my question is: how do i make a dll that I compile from vb.net code register and work like one compiled as an ActiveX dll in VB6? The IDE of my copy of visual basic.net does...
0
by: Will Pittenger | last post by:
I have a Windows program C# .NET solution where when I update its XML documentation, some tags are not recognized and turned into the corresponding HTML. Those tags include <c>, <code>, <para>,...
6
by: John Mark Howell | last post by:
BlankDoes anyone know what all HTML tags are allowed in the XML doc tags? Example, I know by experience that <h1> tags are allowed. What other tags are allowed? The MSDN is not clear about this. ...
1
by: Lasse Vågsæther Karlsen | last post by:
I've been using XML Documentation in my class libraries since I discovered this, and I have been using NDoc to produce help files from the xml files so that the documentation is available outside...
4
by: Spike | last post by:
I purchased Visual Basic .NET Deluxe Learning edition, version 2003. When I got to step 3 of the installation, the installer couldn't find the help files on any of the included discs, and so...
21
by: Jim | last post by:
I am trying to write an HTTP/HTTPS proxy server in VB.Net 2005. But, I don't really even know how the internal workings of a proxy should act. Does anyone have anything on the protocols used in...
10
by: dba123 | last post by:
Why am I getting this error for Budget? Error: An exception of type 'System.FormatException' occurred in mscorlib.dll but was not handled in user code Additional information: String was not...
10
by: Lloyd Dupont | last post by:
Let say I have 2 methods: void BeginGroup(); void BeginGroup(string msg); when I want to refer to them I write /// <see cref="BeginGroup"/> But this cause a compiler warning, where my...
0
by: DolphinDB | last post by:
Tired of spending countless mintues downsampling your data? Look no further! In this article, you’ll learn how to efficiently downsample 6.48 billion high-frequency records to 61 million...
0
by: ryjfgjl | last post by:
ExcelToDatabase: batch import excel into database automatically...
0
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
0
by: Vimpel783 | last post by:
Hello! Guys, I found this code on the Internet, but I need to modify it a little. It works well, the problem is this: Data is sent from only one cell, in this case B5, but it is necessary that data...
0
by: jfyes | last post by:
As a hardware engineer, after seeing that CEIWEI recently released a new tool for Modbus RTU Over TCP/UDP filtering and monitoring, I actively went to its official website to take a look. It turned...
1
by: PapaRatzi | last post by:
Hello, I am teaching myself MS Access forms design and Visual Basic. I've created a table to capture a list of Top 30 singles and forms to capture new entries. The final step is a form (unbound)...
0
by: CloudSolutions | last post by:
Introduction: For many beginners and individual users, requiring a credit card and email registration may pose a barrier when starting to use cloud servers. However, some cloud server providers now...
1
by: Shællîpôpï 09 | last post by:
If u are using a keypad phone, how do u turn on JavaScript, to access features like WhatsApp, Facebook, Instagram....
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.