Documenting Class Libraries

  • Thread starter Thread starter Matthijs ter Woord
  • Start date Start date
M

Matthijs ter Woord

Hi,

I want to document my class libraries' API's. They're all in C#. I could use
the inline documentation comments, but I feel, using inline documentation
comments makes the source code messy. Are there any opensource tools which
allow me to document my library without using the source code?


Greets,

Matthijs ter Woord
 
NDoc uses the C# xml documentation files, So i still need to enter ugly
comments in my code.


Greets
 
Current best practices state that you should associate your code as closely
with the documentation as possible. This has been a best practice for
better part of a decade. There is even a branch of computer science called
Literate Programming where the code is extracted from the documentation, not
the other way around.

If you don't want to look at the documentation, you can always collapse it.
When you create a standard code block, Visual Studio gives one of those
little "-" controls in the left margin. If you hit it, the documentation
collapses.

--
--- Nick Malik [Microsoft]
MCSD, CFPS, Certified Scrummaster
http://blogs.msdn.com/nickmalik

Disclaimer: Opinions expressed in this forum are my own, and not
representative of my employer.
I do not answer questions on behalf of my employer. I'm just a
programmer helping programmers.
 
Matthijs said:
NDoc uses the C# xml documentation files, So i still need to enter
ugly comments in my code.
Click to expand...
So? They're not ugly. (IMHO).
If you get Ghostdoc as well, you can make this very easy, as ghostdoc
already gives you good comments to start with with a press of a
keycombination.

http://www.roland-weigelt.de/ghostdoc/

Also, with XML comments you can include external written comments.
Afterall it's for sourcecode documentation, and the best thing you can
have is to have a close connection between sourcecode and the actual
documentation. Don't confuse it with code 'design' documentation
though, this is pure for a reference manual!

In VS.NET, set the Xml comment backgrounds to grey. This will also
give a better visual appearance for the xml comments and mark starts of
your methods visually, which makes code easier to read.

FB


--
 
Back
Top