TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
In answer to your "what this (<br />:) stuff is" question, your
developer suggested you use the entity form for the symbols < (<)
and > (>). 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.
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 <br />: 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.
