473,326 Members | 2,136 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,326 software developers and data experts.

XML tags and /doc switch

I came across the reference to the self-documenting comment tags that can be
embedded in the C# source code (e.g., ///<summary>) and used to generate an
XML file that describes the code. This looks interesting, but I have some
concerns.

1. If I enable this for a single project, add some tags for most objects,
specify the XML output file name, then I can build the project with no
problems and the XML file is created -- but if I attempt to build the
solution it complains that not all of the members of every structure I
defined have a tag associated with them! Why this discrepency and how do I
convince the solution build to permit this?

2. I am permitted to enter the name of the XML file to generate, but I
cannot put a relative path in front of the name -- if I do then the "Apply"
button erases the text that I entered.

3. Is there some facility available that will convert the genersted XML into
a documentation dictionary? The XML file is cool, but I do not see it as
being much use outside of the IDE itself.

4. The documentation indicates that the commentes entered are used for
intellisense and the object browser displays -- do I have to generate the
XML file to get these beefits, or merely define the tags?

-Ken
Nov 16 '05 #1
1 2202
n!
> 1. If I enable this for a single project, add some tags for most objects,
specify the XML output file name, then I can build the project with no
problems and the XML file is created -- but if I attempt to build the
solution it complains that not all of the members of every structure I
defined have a tag associated with them! Why this discrepency and how do I
convince the solution build to permit this?
They are only warnings, you can ignore them if you wish. The compiler is
complaining because you've stated you want documentation, but you haven't
documented your publicly accessible objects. Which means the documentation
will be incomplete. You don't need to document *all* classes\methods, only
publicly accessible ones. So mark classes that you don't intend to be
accessed from elsewhere 'internal'. The same goes for methods\properties
etc, mark them private or internal as required.
3. Is there some facility available that will convert the genersted XML into a documentation dictionary? The XML file is cool, but I do not see it as
being much use outside of the IDE itself.
I use ndoc (http://ndoc.sourceforge.net) which is excellent (erm, if that
link doesn't work try searching for ndoc on sourceforge. Our http web access
is currently broken and I can't verify I remembered it correctly).
4. The documentation indicates that the commentes entered are used for
intellisense and the object browser displays -- do I have to generate the
XML file to get these beefits, or merely define the tags?


You need to give the tags a body if you actually want them to display
something. The XML file is used for class libraries that are not a part of
your project but are referenced by your assembly (IIRC).

n!
Nov 16 '05 #2

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

Similar topics

1
by: Brent Eamer | last post by:
How do I assign a form field to a value parameter of the sql tag? Ie) I want a query that will search for an item in the database based on the value of a hidden form field All the examples I...
8
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>,...
2
by: Nedu N | last post by:
Hi, I want to display the XML tags (for the the XML tags is the data that is stored in a table) on the datagrid using the datasets. But since the data itself is the XML tag it doesn't appera on...
2
by: Brian Bischof | last post by:
To get my formatting to work with Firefox and IE browsers, I have to be very careful about the layout. So I'm removing all the Style tags that set the Height and Width values (and some of these...
0
by: Allan Ebdrup | last post by:
I have a ascx webcontrol that I register with: %@ Register Src="../Controls/Default/Library/Basket/Basket.ascx" TagName="Basket" TagPrefix="uc1" %> and instantiate on the page with:...
2
by: dennis.sprengers | last post by:
Ik ben bezig met een eigen UBB editor. Als iemand aan het typen is, zorgt CTRL-B voor een \-tag en nogmaals CTRL-B voor een \ tag. Als je eerst een selectie maakt en dan CTRL-B drukt, wordt de...
2
by: steve | last post by:
I get "content is not allowed between the opening and closing tags" in the visual studio 2005 IDE in relation to a Telerik RadTabstrip control, when I switch from design to source view. I cant...
3
by: Paul Moore | last post by:
I'd like to write some scripts to analyze and manipulate my music files. The files themselves are in MP3 and FLAC format (mostly MP3, but FLAC where I ripped original CDs and wanted a lossless...
10
by: Thomas M. Farrelly | last post by:
hi, I have just released a javascript framework. It is at tin-tags.org. I am greateful for any comments. Thanks in advance.
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...
1
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: 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: 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: Defcon1945 | last post by:
I'm trying to learn Python using Pycharm but import shutil doesn't work
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: af34tf | last post by:
Hi Guys, I have a domain whose name is BytesLimited.com, and I want to sell it. Does anyone know about platforms that allow me to list my domain in auction for free. Thank you
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...
0
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 3 Apr 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome former...

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.