Code documentation.

  • Thread starter Thread starter Guest
  • Start date Start date
G

Guest

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
 
Fredrik said:
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 :).
Click to expand...

With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/d...ef/html/vclrfTagsForDocumentationComments.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
 
Arnaud Debaene said:
With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/d...ef/html/vclrfTagsForDocumentationComments.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.
Click to expand...
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.
 
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!
Click to expand...

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.
 
Mehdi said:
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.
Click to expand...

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.
 
Arnaud Debaene said:
With C# and VB.NET, you can use specially formatted comments (see
http://msdn.microsoft.com/library/d...ef/html/vclrfTagsForDocumentationComments.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.
Click to expand...
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?
 
Fredrik said:
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.
Click to expand...

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
 
Arnaud Debaene said:
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.
Click to expand...
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.
 
Arnaud Debaene said:
HTML Help Workshop should be fine for what you want :
http://www.microsoft.com/downloads/...34-c8a6-452f-9aa0-d597d16580cc&DisplayLang=en
Click to expand...

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...
 
Fredrik Olsson said:
Lets See:
/// @param foo amount of bars.
And
/// <param name="foo">amount of bars</param>

Not close if you ask me
Click to expand...

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.
Click to expand...

They could certainly have defined C# to have JavaDoc syntax, but they
decided not to, presumably preferring the XML form - as I do.
 
Fredrik Olsson said:
@[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!
Click to expand...

I agree. And XML documentation gets even more unreadable when things like
hyperlinks and HTML new line tags are include.
 
Fredrik said:
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.
Click to expand...
It's NDoc that will the generate the doc with the "Look&Feel" you want!

Arnaud
MVP - VC
 
Back
Top