473,320 Members | 1,933 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,320 software developers and data experts.

Documenting Class Libraries

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
Aug 3 '05 #1
4 1407
See NDoc on sourceforge

-Atul, Sky Software http://www.ssware.com
Shell MegaPack ActiveX & .Net
Drop In Windows Explorer like Shell Browsing GUI controls for your app.
"Matthijs ter Woord" <ma**************@gmail.com> wrote in message
news:O1*************@TK2MSFTNGP14.phx.gbl...
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

Aug 3 '05 #2
NDoc uses the C# xml documentation files, So i still need to enter ugly
comments in my code.
Greets

"Atul" <atulatsswaredotcom> wrote in message
news:eO*************@TK2MSFTNGP10.phx.gbl...
See NDoc on sourceforge

-Atul, Sky Software http://www.ssware.com
Shell MegaPack ActiveX & .Net
Drop In Windows Explorer like Shell Browsing GUI controls for your app.
"Matthijs ter Woord" <ma**************@gmail.com> wrote in message
news:O1*************@TK2MSFTNGP14.phx.gbl...
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


Aug 3 '05 #3
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 ter Woord" <ma**************@gmail.com> wrote in message
news:O1*************@TK2MSFTNGP14.phx.gbl...
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

Aug 3 '05 #4
Matthijs ter Woord wrote:
NDoc uses the C# xml documentation files, So i still need to enter
ugly comments in my code.
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


"Atul" <atulatsswaredotcom> wrote in message
news:eO*************@TK2MSFTNGP10.phx.gbl...
See NDoc on sourceforge

-Atul, Sky Software http://www.ssware.com
Shell MegaPack ActiveX & .Net
Drop In Windows Explorer like Shell Browsing GUI controls for your
app.
"Matthijs ter Woord" <ma**************@gmail.com> wrote in message
news:O1*************@TK2MSFTNGP14.phx.gbl...
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?

--
------------------------------------------------------------------------
Get LLBLGen Pro, productive O/R mapping for .NET: http://www.llblgen.com
My .NET blog: http://weblogs.asp.net/fbouma
Microsoft MVP (C#)
------------------------------------------------------------------------
Aug 4 '05 #5

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

Similar topics

2
by: Rony | last post by:
A question on python source documentation. Does there exist a standard for documenting code ? I've included here an example generated by pydoc of one of my modules. Is this the right way or is it...
5
by: Isaac Rodriguez | last post by:
Hi, Are there any standarized ways of documenting Python code? When I check the __doc__ attribute of the standard modules, the results are kind of plain. Is everyone using this style? Since...
1
by: rinku24 | last post by:
We have two C++ libraries (Unix Shared objects) with the same class name and no namespace. Is there any way to load both the libraries and selectivly create the instance of the class from...
2
by: Lasse Vågsæther Karlsen | last post by:
I notice that if I use this syntax: def classname: ... ## # closes the database connection and releases the resources. def close(self): .... ##
1
by: strauss.sean | last post by:
I have been asked to begin documenting the ongoing development and changes to a database that I maintain. Not the entry of data; this is about the changes to how tables are restructured, and any...
4
by: geoffblanduk_nospam | last post by:
I have an NUnit test plan with well over 500 tests. I now need to produce a test plan document for these tests - documenting them one by one with Word is a painfull task. I was thinking that...
1
by: Brett | last post by:
I'd like to have all of my documentation in one place. I use the following for documenting code: - attributes for certain types of documentation - use of the C# generated inline XML...
4
by: Matthijs ter Woord | last post by:
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....
8
by: Spleenwort | last post by:
With regard to XML comments in c#. I think that #regions should be self-documenting relative to XML comments or that a <region> tag should be defined and auto-inserted when you type #region...
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
by: ryjfgjl | last post by:
ExcelToDatabase: batch import excel into database automatically...
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: PapaRatzi | last post by:
Hello, I am teaching myself MS Access forms design and Visual Basic. I've created a table to capture a list of Top 30 singles and forms to capture new entries. The final step is a form (unbound)...
0
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...
0
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...

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.