Editing files that were generated from Javadocs once?

Subject: Editing files that were generated from Javadocs once?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Nurit Zur <nurit286 -at- yahoo -dot- com>
Date: Wed, 23 Aug 2006 09:08:40 -0400

Nurit Zur wondered: <<We use Javadocs to generate API reference guides. However, we do not have access to the code and the developers do not always copy the updated text to the source code (almost never would be more accurate). Therefore, next editing round we have to edit again what we have already edited.>>

Even programming managers will probably understand that doing exactly the same thing every 6 months is inefficient and error-prone. The obvious solution is to make it part of the programmer's responsibility to update the code and to hold them accountable for doing the job right. Of course, "accountability" and "responsibility" are words that seem to have gone out of fashion in North America (can't speak for the rest of the world), and programming managers aren't always as clueful as one might wish. That being the case:

<<Is there a tool or method that enables to "single source" the comments that are used to generate the API reference guide? Either a tool that copies all the text back to the original files or a method of working that enables to use or copy the same text to both the source files and the documentation files.>>

I can't speak to JavaDoc, but I do recall that it seemed quite easy to do in Borland's Delphi programming environment. I can't tell you the details from the programmer's perspective because I only worked with the text, not with the code, but here's the gist of it: Essentially, the interface labels (e.g., menu and field names), dialog box text, error messages, etc. could be stored in an external resource/reference file. Instead of typing this text directly into the code, the programmers imported it by reference during compiling of the software. Your programmers should be able to tell you how they could do the same thing; it should either be supported directly by their programming environment, or trivially easy to program.

At my former employer, the developers shipped me a text-format version of the file, and I either printed it and annotated it manually with red pen, or edited in Word using revision tracking so they could approve each change. (Different programmers, different preferences.) So long as you save the file in .doc format to enable revision tracking, and in "text" format when the editing is complete so it can be reimported into the programming environment, editing in Word works well. Never had a single problem.

There are two big gotchas in this approach: First, you are seeing the text out of context (i.e., not surrounded by the actual program code), so you have to review ("proofread") the interface after compilation to ensure that the labels are correct. (Alternatively, you call up the programmer and ask "What function is the word 'tanstaafl' associated with?") You can also walk through the interface one feature at a time, then search the text file to find and correct each chunk of text. Second, you have to be scupulously careful not to screw up any of the punctuation or formatting; most software uses odd syntax, such as '' or & before special characters, that must not be damaged.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart ghart -at- videotron -dot- ca

(try geoffhart -at- mac -dot- com if you don't get a reply)


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

Editing files that were generated from Javadocs once: From: Nurit Zur

Previous by Author: Browseable vs browsable?
Next by Author: A question about evaluations?
Previous by Thread: Editing files that were generated from Javadocs once
Next by Thread: Re: Editing files that were generated from Javadocs once

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

Sponsored Ads