471,344 Members | 1,532 Online
Bytes | Software Development & Data Engineering Community
Post +

Home Posts Topics Members FAQ

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

Code documentation.

Hello.

For Java there is javadac, for Obj-C headerdoc2html, for C doxygen, and even
for good old VB 6 there is VBDox.

But I have found no suitable tool for documenting my .net code to get
documentation that is consistent with what MSDN offers and .net-develoepers
are used to.

I guess I have only searched int he wrong places, or with the wrong keywords
:).

Any halpt is apreciated.

regards
//Fredrik Olsson
Jul 22 '05 #1
12 2754
Fredrik Olsson wrote:
Hello.

For Java there is javadac, for Obj-C headerdoc2html, for C doxygen,
and even for good old VB 6 there is VBDox.

But I have found no suitable tool for documenting my .net code to get
documentation that is consistent with what MSDN offers and
.net-develoepers are used to.

I guess I have only searched int he wrong places, or with the wrong
keywords :).


With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/de...onComments.asp
for example). The /doc compiler option will cause the compiler to spit out
an XML file containing the documentation. You can then use various tools to
generate the help in whatever format you like. NDoc
(http://ndoc.sourceforge.net/) is very good for example.

Arnaud
MVP - VC
Jul 22 '05 #2
"Arnaud Debaene" wrote:
Fredrik Olsson wrote:
Hello.

For Java there is javadac, for Obj-C headerdoc2html, for C doxygen,
and even for good old VB 6 there is VBDox.

But I have found no suitable tool for documenting my .net code to get
documentation that is consistent with what MSDN offers and
.net-develoepers are used to.

I guess I have only searched int he wrong places, or with the wrong
keywords :).


With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/de...onComments.asp
for example). The /doc compiler option will cause the compiler to spit out
an XML file containing the documentation. You can then use various tools to
generate the help in whatever format you like. NDoc
(http://ndoc.sourceforge.net/) is very good for example.

I shudder!

Javadoc, doxygen VBDox, headerdoc2html and all others I have looked at works
very similar so doing to hard bulk "porting" of documentation can quite
easily be made with a search and replace, do it with regexp if you want it
99% perfect.

But this is apart from being "different" cluncier, harder to read and
maintain. It is not as if other code documentation tools has net been around.
Having an intermediate xml-format is good, I like it. But making it up to the
user to create the xml-code is horrible, the documentation compiler should do
that!

I'll go around and see if doxygen can be made into generating xml-documents
compatible with wath the C# compiler makes. And if not, well... I'll just
have to add to the project time...

Thanks for the help, even if I did not like the answer :).

regards
/// Fredrik Olsson.
Jul 22 '05 #3
On Fri, 15 Jul 2005 03:47:01 -0700, Fredrik Olsson wrote:
But this is apart from being "different" cluncier, harder to read and
maintain. It is not as if other code documentation tools has net been around.
Having an intermediate xml-format is good, I like it. But making it up to the
user to create the xml-code is horrible, the documentation compiler should do
that!


I think that you have overlooked something here. In the current version of
Visual Studio (2003), there is effectively no automatic comment formatting
for Visual Basic (this will appear in VS 2005). However, in C#, simply
place the cursor above any method or member variable and type 3 slashes
(///). The XML comment are going to be automatically generated for you.
You'll just have to fill the blanks. And if you want to add extra info such
as remarks or description of exceptions thrown, simply type < and
intellisense will pop up to give you all the possible XML comment tags you
can use; choose one and the opening and closing tags will be automatically
generated. Once you've got your XML doc done, launch NDoc, click on a
button, wait a few seconds (or minutes for a big project) and that's your
documentation done in whatever format you want: html pages, HTML help file,
msdn style, javadoc style... Having never used another doumentation
utility, i can't compare, but the VS + NDoc makes me quite happy for this
matter.
Jul 22 '05 #4
"Mehdi" wrote:
On Fri, 15 Jul 2005 03:47:01 -0700, Fredrik Olsson wrote:
But this is apart from being "different" cluncier, harder to read and
maintain. It is not as if other code documentation tools has net been around.
Having an intermediate xml-format is good, I like it. But making it up to the
user to create the xml-code is horrible, the documentation compiler should do
that!


I think that you have overlooked something here. In the current version of
Visual Studio (2003), there is effectively no automatic comment formatting
for Visual Basic (this will appear in VS 2005). However, in C#, simply
place the cursor above any method or member variable and type 3 slashes
(///). The XML comment are going to be automatically generated for you.
You'll just have to fill the blanks.


If I would be developing in .net originally it would be quite good. But I am
not, and I do not write the comments manually. My project is quite huge and
PLATFORM INDEPENDENT. Basically it is a ANSI C library with wrappers for C++,
Objective-C, Perl, COM, Pascal, Java, Delphi, and a few others. And not .net
as well.

For the OOP languages (Objective-C not included) the API looks very similar,
only a few changes to make it more comfortable to "native" programmers and
work around weaknesses or take advantage of strengths. But the basics are
allways there.

Keeping a dozen of documentations up to date is a cumbersome task, and is
manly automated so the documentation is "converted" from one source to the
other with in house tools. It is generally no problem at all, because all
documentation tools use the same general syntax so a more or less simple
replace using "sed" is all that is needed, apart from proof-reading. It saves
A BUNCH OF TIME.

But now the xml tags for c# is not even close... which is sad. Since the
other existing (and decades old) methods really are more human-readable as
well.

But no fear, I am writing a hack with flex and bison to parse the javadoc
comments and generate c# compatible comments.
Jul 22 '05 #5
"Arnaud Debaene" wrote:
Fredrik Olsson wrote:
Hello.

For Java there is javadac, for Obj-C headerdoc2html, for C doxygen,
and even for good old VB 6 there is VBDox.

But I have found no suitable tool for documenting my .net code to get
documentation that is consistent with what MSDN offers and
.net-develoepers are used to.

I guess I have only searched int he wrong places, or with the wrong
keywords :).


With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/de...onComments.asp
for example). The /doc compiler option will cause the compiler to spit out
an XML file containing the documentation. You can then use various tools to
generate the help in whatever format you like. NDoc
(http://ndoc.sourceforge.net/) is very good for example.

Stumped on NDoc, it requres a HTML Help 2 compiler, and says I should
install VSHIK 2003. Problem, VSHIK 2003 refuses to install without an
installation of Visual Studio 2003.

Is there a way to install just the HRML Help 2 compiler, or another version
of VSHIK that is buried deeper on the MSDN web page?
Jul 22 '05 #6
Fredrik Olsson wrote:
"Arnaud Debaene" wrote:
Fredrik Olsson wrote:
Hello.

For Java there is javadac, for Obj-C headerdoc2html, for C doxygen,
and even for good old VB 6 there is VBDox.

But I have found no suitable tool for documenting my .net code to
get
documentation that is consistent with what MSDN offers and
.net-develoepers are used to.

I guess I have only searched int he wrong places, or with the wrong
keywords :).


With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/de...onComments.asp
for example). The /doc compiler option will cause the compiler to
spit out
an XML file containing the documentation. You can then use various
tools to
generate the help in whatever format you like. NDoc
(http://ndoc.sourceforge.net/) is very good for example.

Stumped on NDoc, it requres a HTML Help 2 compiler, and says I should
install VSHIK 2003. Problem, VSHIK 2003 refuses to install without an
installation of Visual Studio 2003.

Is there a way to install just the HRML Help 2 compiler, or another
version
of VSHIK that is buried deeper on the MSDN web page?


HTML Help Workshop should be fine for what you want :
http://www.microsoft.com/downloads/d...DisplayLang=en

Arnaud
MVP - VC
Jul 22 '05 #7
Fredrik Olsson wrote:
Keeping a dozen of documentations up to date is a cumbersome task,
and is
manly automated so the documentation is "converted" from one source
to the other with in house tools. It is generally no problem at all,
because all documentation tools use the same general syntax so a more
or less simple replace using "sed" is all that is needed, apart from
proof-reading. It saves
A BUNCH OF TIME.

But now the xml tags for c# is not even close... which is sad. Since
the
other existing (and decades old) methods really are more
human-readable as well.


I don't get your point here : I think C# style comments are very similar to,
say, Doxygen documentation. XML has the advantage of being more easily
parsable because there is an "end" mark for each element, whereas in many
other formats, the "end" of a given element if often marked by a new line, a
new paragraph and the like.

Arnaud
MVP - VC
Jul 22 '05 #8
"Arnaud Debaene" wrote:
Fredrik Olsson wrote:
Keeping a dozen of documentations up to date is a cumbersome task,
and is
manly automated so the documentation is "converted" from one source
to the other with in house tools. It is generally no problem at all,
because all documentation tools use the same general syntax so a more
or less simple replace using "sed" is all that is needed, apart from
proof-reading. It saves
A BUNCH OF TIME.

But now the xml tags for c# is not even close... which is sad. Since
the
other existing (and decades old) methods really are more
human-readable as well.


I don't get your point here : I think C# style comments are very similar to,
say, Doxygen documentation. XML has the advantage of being more easily
parsable because there is an "end" mark for each element, whereas in many
other formats, the "end" of a given element if often marked by a new line, a
new paragraph and the like.

Lets See:
/// @param foo amount of bars.
And
/// <param name="foo">amount of bars</param>

Not close if you ask me, well searching for the regexp "@param\s(\S*)\s([\S
]*?)" and replacing with "<param name="\1">\2</param>" works. And was easy
enough to set up as a simply batch script.
The rest was not quite as easy.

I do agree that the c# way is easier to parse for a _program_. But if the
developer where ment to help the compiler parse the code, then we would be
writing code in MSIL assembly instructions. It is not really hard to write a
small hack that parse the documentation tags that has been in use for decades
by virtually every other tool available, and turn it into what c# uses. I did
it for the subset I use in in a couple of hours using Perl.

So I can not really see why the c# compiler can not do it. The old fashioned
way is really Much more readable to a human, xml is not really ment to be
human-readable in the same way.

@[what it is] [what it is called] [what it does]
Clear and simple.

<[what it is] [tag depending on what it is]="[what it is called]">what it
does</[what it is again]>
Easier for an xml-parser yes, for a human to read and write? NO!

And then you have even more stuff that is easy to do in the good old
fashioned way that everyone else uses; paragraphs. Simply have an empty line.
Looks good in your code, looks good in the genereted documentation. And no,
the end-marker is not a new line. The end marker is the next non in-line tag.
Jul 22 '05 #9
"Arnaud Debaene" wrote:
Fredrik Olsson wrote:
"Arnaud Debaene" wrote:
Fredrik Olsson wrote:
Hello.

For Java there is javadac, for Obj-C headerdoc2html, for C doxygen,
and even for good old VB 6 there is VBDox.

But I have found no suitable tool for documenting my .net code to
get
documentation that is consistent with what MSDN offers and
.net-develoepers are used to.

I guess I have only searched int he wrong places, or with the wrong
keywords :).

With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/de...onComments.asp
for example). The /doc compiler option will cause the compiler to
spit out
an XML file containing the documentation. You can then use various
tools to
generate the help in whatever format you like. NDoc
(http://ndoc.sourceforge.net/) is very good for example.

Stumped on NDoc, it requres a HTML Help 2 compiler, and says I should
install VSHIK 2003. Problem, VSHIK 2003 refuses to install without an
installation of Visual Studio 2003.

Is there a way to install just the HRML Help 2 compiler, or another
version
of VSHIK that is buried deeper on the MSDN web page?


HTML Help Workshop should be fine for what you want :
http://www.microsoft.com/downloads/d...DisplayLang=en


Yes it works, and it is what I use to genereate the documenattion for the
COM-component to use in old Visual Basic 6, VBScript and addins for Office.
But I am afraid it just works, it does not generate documentation with the
look and feel of modern .net documentation as provided by Micrsooft with more
modern Visual Studio. It just looks very unprofessional if the documentation
is not on par with todays standrds.

Or does .net developers not care? Java developers are very picky and can
throw something away if the documentation is not up to their standrds without
even looking further into what your product offers. But then, the Java
developers have quite high standards... sometimes unreasonably so; even
refering to your objects in the wrong tense can make them go berzerk :). But
on the bright side, no developer has ever had trouble picking up any other
developers work...
Jul 22 '05 #10
Fredrik Olsson <Fr***********@discussions.microsoft.com> wrote:
Lets See:
/// @param foo amount of bars.
And
/// <param name="foo">amount of bars</param>

Not close if you ask me
Agreed, but I suspect the other way round... I think the latter makes
it *far* clearer that the name of the parameter is "foo". I come from a
Java background, but I still far prefer the C# way of doing things when
it comes to documentation.
So I can not really see why the c# compiler can not do it.


They could certainly have defined C# to have JavaDoc syntax, but they
decided not to, presumably preferring the XML form - as I do.

--
Jon Skeet - <sk***@pobox.com>
http://www.pobox.com/~skeet
If replying to the group, please do not mail me too
Jul 22 '05 #11
Fredrik Olsson <Fr***********@discussions.microsoft.com> wrote:
@[what it is] [what it is called] [what it does]
Clear and simple.

<[what it is] [tag depending on what it is]="[what it is called]">what it
does</[what it is again]>
Easier for an xml-parser yes, for a human to read and write? NO!


I agree. And XML documentation gets even more unreadable when things like
hyperlinks and HTML new line tags are include.
Jul 22 '05 #12
Fredrik Olsson wrote:

Yes it works, and it is what I use to genereate the documenattion for
the
COM-component to use in old Visual Basic 6, VBScript and addins for
Office.
But I am afraid it just works, it does not generate documentation
with the
look and feel of modern .net documentation as provided by Micrsooft
with more
modern Visual Studio. It just looks very unprofessional if the
documentation
is not on par with todays standrds.

It's NDoc that will the generate the doc with the "Look&Feel" you want!

Arnaud
MVP - VC
Jul 22 '05 #13

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

1 post views Thread by Brian Beck | last post: by
6 posts views Thread by Mario T. Lanza | last post: by
12 posts views Thread by Steven T. Hatton | last post: by
67 posts views Thread by Steven T. Hatton | last post: by
25 posts views Thread by Alvin Bruney | last post: by
232 posts views Thread by robert maas, see http://tinyurl.com/uh3t | last post: by

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.