473,233 Members | 1,437 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,233 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 2835
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 thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

1
by: Brian Beck | last post by:
Hi. I'm having some problems with code based directly on the following httplib documentation code: http://www.zvon.org/other/python/doc21/lib/httplib-examples.html I've included the code and...
6
by: Mario T. Lanza | last post by:
Greetings, I don't know about you guys but on many occasions I've asked myself whether or not someone else has solved a particular programming issue -- whether or not they developed a clever...
12
by: Steven T. Hatton | last post by:
This is something I've been looking at because it is central to a currently broken part of the KDevelop new application wizard. I'm not complaining about it being broken, It's a CVS images. ...
67
by: Steven T. Hatton | last post by:
Some people have suggested the desire for code completion and refined edit-time error detection are an indication of incompetence on the part of the programmer who wants such features. ...
0
by: XSD-optimist | last post by:
I am trying to generate the classes for an XSD schema using the Microsoft XSD Object Code Generator (XSDObjGen). I am having a schema that contains the definition of the following: 1. a complex...
25
by: Alvin Bruney | last post by:
C# is great but it does have some short comings. Here, I examine one of them which I definitely think is a shortcoming. Coming from C++, there seems to be no equivalent in C# to separate code...
232
by: robert maas, see http://tinyurl.com/uh3t | last post by:
I'm working on examples of programming in several languages, all (except PHP) running under CGI so that I can show both the source files and the actually running of the examples online. The first...
0
by: jianzs | last post by:
Introduction Cloud-native applications are conventionally identified as those designed and nurtured on cloud infrastructure. Such applications, rooted in cloud technologies, skillfully benefit from...
0
by: abbasky | last post by:
### Vandf component communication method one: data sharing ​ Vandf components can achieve data exchange through data sharing, state sharing, events, and other methods. Vandf's data exchange method...
2
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 7 Feb 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:30 (7.30PM). In this month's session, the creator of the excellent VBE...
0
by: fareedcanada | last post by:
Hello I am trying to split number on their count. suppose i have 121314151617 (12cnt) then number should be split like 12,13,14,15,16,17 and if 11314151617 (11cnt) then should be split like...
0
Git
by: egorbl4 | last post by:
Скачал я git, хотел начать настройку, а там вылезло вот это Что это? Что мне с этим делать? ...
0
by: MeoLessi9 | last post by:
I have VirtualBox installed on Windows 11 and now I would like to install Kali on a virtual machine. However, on the official website, I see two options: "Installer images" and "Virtual machines"....
0
by: DolphinDB | last post by:
The formulas of 101 quantitative trading alphas used by WorldQuant were presented in the paper 101 Formulaic Alphas. However, some formulas are complex, leading to challenges in calculation. Take...
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
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...

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.