Re: Commented APIs in Java

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

Thanks Guy and Tony for your suggestions.
All of these have been used unsuccessfully in these Java files: <br>, <br><br>, and <br />.
That is, they can be seen in the HTML doc and they don't cause line breaks.
Grasping at straws: Could the angle of the break have any affect? <br /> vs <br \>

Karen

"We're all in this alone." --Lily Tomlin


On Mar 2, 2012, at 11:13 AM, Tony Chung wrote:

> 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


References:
Commented APIs in Java: From: Karen Felker
Re: Commented APIs in Java: From: Tony Chung

Previous by Author: Commented APIs in Java
Next by Author: RE: More Low Paying Jobs
Previous by Thread: Re: Commented APIs in Java
Next by Thread: Beta Tester's Review of MadCap Flare 8


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

Sponsored Ads


Sponsored Ads