search

AaronNGray / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Class description font color bleeds over into other classes in the class index #259

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
What steps will reproduce the problem?

1. Change the font for the description of a class to red and make sure to
terminate your font tag.  For example, for LABKEY.GridView in the LabKey API:

  * @description <font color="red">NOTE: This class is now DEPRECATED in
favor of the {@link LABKEY.ext.EditorGridPanel}  class. </font>
  * @class <font color="red">NOTE: This class is now DEPRECATED in favor of
the {@link LABKEY.ext.EditorGridPanel} class.</font>

(Yes, we really, really wanted to emphasize that this class was deprecated)

2. Generate docs and look at the class index.

Observe: The font for the class description remains red for all classes
below the class whose font was changed to red.

Expect: Terminated font tags affect only enclosed html.  Do not expect to
change font color for other class descriptions.

What version of the product are you using? On what operating system?

JSDoc Toolkit v2.3.2, updated via subversion last week.  Windows.

Please provide any additional information below.

Workaround:

Change the font color for the next class listed in order in your class list
to black.  All class descriptions from this one downwards will return to
black. Phew!

For example, I edited the LABKEY.Message class:

/**
 * @namespace <font color="black">LabKey Email Notification Helper class.
 * This class provides static methods to generate an email notification
message that gets sent from the
 * LabKey SMTP server.</font>
 */

I can send files if that helps, but this little bug seems straightforward
to repro.

Original issue reported on code.google.com by ekaynel...@gmail.com on 16 Oct 2009 at 1:41

GoogleCodeExporter commented 9 years ago 
I can't reproduce this bug, can you create a very simple example that shows it 
and attach?

Original comment by micmath on 8 Nov 2009 at 8:47

GoogleCodeExporter commented 9 years ago 
I'll try to put together a simple example later this week.  In the mean time, it
might be easy to just look at a zip of the js files where this turned up.  The
GridView.js file has red font styling in its first annotations to indicate
deprecation.  The Message.js file has black font styling in its first 
annotations to
make sure that the red styling from GridView.js actually gets turned off in the 
class
list.  

You can see the final results here (with linked source code, thanks to the
jsdoc-toolkit!):
https://www.labkey.org/download/clientapi_docs/javascript-api-9.3-draft/index.ht
ml

Thanks very much for taking a look.

Original comment by ekaynel...@gmail.com on 8 Nov 2009 at 10:05

Attachments:

GoogleCodeExporter commented 9 years ago 
The template that generates the "Class Index" is jsdoc/index.tmpl. If you take 
a look at that you'll see that the 
class descriptions are passed through summarize(), which is defined in 
publish.js. The summarize method 
trims away all the text after the first sentence. You are writing descriptions 
that have an opening FONT tag, 
but the closing FONT tag is *after* the end of the sentence, therefore 
summarize() trims away the closing tag.

You can solve this a few ways. Most easily you can move the FONT closing tag so 
that it is before the end of 
the first sentence.

A better solution would be to add a @deprecated tag to the classes that are 
deprecated, then modify 
jsdoc/index.tmpl so that it has the following:

<for each="thisClass" in="data">
<div>
    <h2>{+(new Link().toSymbol(thisClass.alias))+}</h2>
    <span{! if (thisClass.comment.getTag("deprecated").length) {output += " style='color: red'";} 
!}>{+resolveLinks(summarize(thisClass.classDesc))+}</span>
</div>
<hr />
</for>

Original comment by micmath on 8 Nov 2009 at 10:54

GoogleCodeExporter commented 9 years ago 
Sigh.  So clear in retrospect.  Thank you for your sleuthing -- I forgot about 
the
limitation on the first sentence.  

Thank you very much for the suggested alteration to the index.tmpl.  That's
definitely the right way to do this.

Original comment by ekaynel...@gmail.com on 9 Nov 2009 at 1:12