Commented APIs in Java

Subject: Commented APIs in Java
From: Karen Felker <akaren -at- earthlink -dot- net>
To: Tech Writers <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 2 Mar 2012 10:17:18 -0800

A little background: I'm working at a software company where we produce our documentation in DITA/XML files that are stored in the same repository as product code. At build time, our files are wrapped up with hundreds of Java files that describe the APIs. The documentation is installed with the product and opens in HTML, with the APIs appearing on one of the browser tabs.

The API files have been written over the last 20 years by multiple engineers. I've been asked to clean up some of the inconsistencies in spelling and formatting, in my spare time. In these Java files, the lines that appear in documentation are commented out, that is, they begin with /**, followed by * on each successive line, and end with */. In the HTML output, a class name is followed by a brief description, then smaller headings introduce Fields, Constructors, and Methods. Two columns format the content after each of these smaller headings. The left column for Methods, for example, shows the name of a method, the right column describes what the method does. Its parameters are introduced with the word Parameters:, followed by a bulleted list; what the method returns is introduced with… you get the idea.

My Problem Today: One class evaluates arithmetic functions. Apparently, the engineer who documented this class wanted to begin each line of the description with a word in bold font, followed by text. He used this formatting:

/**
* This evaluator supports these arithmetic functions:
* <p>
* <b>Function Name:</b> ADD<br />
* <b>Arguments:</b> num1, num2 (Must be convertible to double.)<br />
* <b>Description:</b> num1 + num2
* </p>
*… etc.

When this formatting is converted to HTML, it appears on the right-hand column looks like this:

This evaluator supports these arithmetic functions:
Function Name: ADD<br /> Arguments: num1, num2 (Must be
convertible to double.)<br />Description: num1 + num2

I've been asked to make the <br /> disappear. The engineer in charge of making builds work suggested, in an email, that I try using &lt;br /&gt: instead.

He's in a different time zone, so I can't question him directly. I'm hoping someone in this group can give me some insight into what this (&lt;br /&gt:) stuff is and, if that doesn't work, what else I might use.

Karen

"Let us read and let us dance ... two amusements that will never do any harm to the world."-- Voltaire


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.

Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.

http://bit.ly/doc-to-help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


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

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

Previous by Author: Re: Help with fake names issue
Next by Author: Re: Commented APIs in Java
Previous by Thread: TechWhirl: Technical Communications Recap for March 2, 2012
Next by Thread: Re: Commented APIs in Java


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

Sponsored Ads


Sponsored Ads