RE: .NET and javadoc (SIDELINE FROM: Directions for tomorrow's techwriting)

Subject: RE: .NET and javadoc (SIDELINE FROM: Directions for tomorrow's techwriting)
From: "Richard Smith" <richard -dot- smith -at- windriver -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 26 Apr 2002 09:48:32 -0700


I have not used document X, so I can't offer any useful comments on it. I
have used Javadoc, and some others. Most of these tools work by parsing the
actual source files, extracting packages, classses, methods, params, and so
forth, along with comments, see-alsos, notes, etc. that the developers (or
sometimes you) put directly in the source. Each tool, if I recall correctly,
uses slightly different syntax for the embedded markup. So the key to making
you life easier is ensuring write to an agreed upon set of coding
conventions that match the doc generation tool you are using.

These tools are nice. AT a minimum, they generate some of the API doct for
you. If you stay on top of things, you can quickly generate new copies of
source/API docs not too long after a new baseline.

I think that most of these tools work for a particular type of source code.
Javadoc only does java. Doxygen does C++, Java, C, and CORBA/IDL. I think
Rational SoDa does this (among other things) too. We also have an in-house
tool that does C, C++, and TCL.

There is usually not much academic learning that goes into using one of
these tools. The ideas are pretty simple. What you need to do is get the
appropriate tools and start running some code through them. Then you can see
how they work and how to get what you want out of the markup.

See what For starters, look at these:
java.sun.com/javadoc
www.doxygen.org

have fun,
Richard




> I've recently been lucky enough to be put on a project which
> is at the very
> first stages of its inception.
> The development team have only just decided that they are
> going to use .NET
> to write the code for the application.
> As a side-effect, my manager has asked me to look at new and
> emerging ways
> of documenting code.
> He's directed me towards Document! X and javadoc as a
> starting point.
> Has anyone used these or similar technologies? What was your
> experience?
> Can you recommend any online learning resources?




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.


Follow-Ups:

Previous by Author: RE: Identify help tool used to create help
Next by Author: Current Agency (Contract) Rates in NYC
Previous by Thread: .NET and javadoc (SIDELINE FROM: Directions for tomorrow's techwriting)
Next by Thread: Searching for a Font - RESOLVED


What this post helpful? Share it with friends and colleagues:


Sponsored Ads