Re: Commented APIs in Java

Subject: Re: Commented APIs in Java
From: Tony Chung <tonyc -at- tonychung -dot- ca>
To: Karen Felker <akaren -at- earthlink -dot- net>
Date: Fri, 2 Mar 2012 11:13:53 -0800

In answer to your "what this (&lt;br /&gt:) stuff is" question, your
developer suggested you use the entity form for the symbols < (&lt;)
and > (&gt;). Unfortunately, this won't work for you because the
purpose of entities is to retain the angle brackets around tags.

However, this JavaDoc guide shows that you could use the <br> (without
the slash) to generate line breaks. JavaDoc doesn't appear to filter
<br /> and <br> the same. I don't know if it's because JavaDoc output
is based on HTML and not XHTML syntax, or if that is just a feature of
the JavaDoc filter.

http://research.cs.queensu.ca/home/cisc124/2001f/Javadoc.html#andHTML

And Robert gave a great reference for overall syntax and style.

-Tony

On Fri, Mar 2, 2012 at 10:17 AM, Karen Felker <akaren -at- earthlink -dot- net> wrote:
> 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.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:

References:
Commented APIs in Java: From: Karen Felker

Previous by Author: TECHWR-L Premium Jobs, Events, and Announcements
Next by Author: Re: Dealing with samples...
Previous by Thread: Commented APIs in Java
Next by Thread: Re: Commented APIs in Java


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

Sponsored Ads


Sponsored Ads