search

AaronNGray / jsdoc-toolkit

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

@example documentation does not explain how to end the example #272

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
The documentation for the @example tag at

http://code.google.com/p/jsdoc-toolkit/wiki/TagExample

doesn't indicate how to indicate that a code example has ended.  This is 
necessary if the @example is embedded in a larger docblock.

For example:

/**
 * Converts a wizzle to a wozzle.
 *
 * @example
 * foo.convert("ffff");
 *
 * NOTE: Only works if the wizzle is less than 100 characters long.
 * 
 * @param {String} s string to convert
 * @return {String}
 */

Original issue reported on code.google.com by ithinkihaveacat on 3 Dec 2009 at 4:48

GoogleCodeExporter commented 9 years ago 
All tags (@example is no exception) end when either: a new tag starts, or the 
doc comment itself ends. There are 
no "ending tags" for any tag.

Are you saying the example you cited doesn't work?

Original comment by micmath on 3 Dec 2009 at 4:52

GoogleCodeExporter commented 9 years ago 
Sorry, I'm having trouble getting jsdoc-toolkit to work at all.  I was 
originally 
interested in @example simply because I was wondering about the syntax (I'm not 
actually generating documentation at this time), and from the URL above I 
couldn't 
figure out how to "close" an @example.  When I get jsdoc working (see issue 
273) I'll 
get back to you--maybe it does "just work" but I think it would be useful if 
the 
documentation either explicitly said, or implied via the example, that closing 
@example 
tags is not necessary.

Original comment by ithinkihaveacat on 4 Dec 2009 at 10:40

GoogleCodeExporter commented 9 years ago 
Yes, it doesn't work the way I expected; in the generated HTML, the "NOTE: Only 
works 
if ..." appears in the code block:

  <pre class="code">foo.convert("ffff");
  NOTE: Only works if the wizzle is less than 100 characters long.</pre>

How do I indicate that the example has ended?

Original comment by ithinkihaveacat on 11 Feb 2010 at 11:11

GoogleCodeExporter commented 9 years ago 
ALL text after @example and before the start of the next tag is considered part 
of the example. if you want to 
have non-example text in your docs you'll need to put it somewhere not in an 
example tag. Or add comments:

@example
foo.convert("ffff");
// NOTE: Only works if the wizzle is less than 100 characters long.

Original comment by micmath on 11 Feb 2010 at 11:30

GoogleCodeExporter commented 9 years ago 
Can you at least mention in the documentation that "inline" examples are not 
supported (as a consequence of the templating potentially being able to move 
the tags 
around?), and that if you want "inline" examples you need to do this 
"manually", such 
as with <pre> tags within a @description block?

Many other documentation tools support inline examples (e.g. phpDocumentor, and 
I 
think javadoc; this is usually done with HTML-like tags like <pre> or <code> 
that can 
be closed) so I think it would be helpful if the documentation mentioned that 
the 
@example tag is not intended to be used to generate "inline" examples, and that 
if 
you want this, you need to do it via HTML markup embedded within a @description 
block?

Original comment by ithinkihaveacat on 11 Feb 2010 at 12:30

GoogleCodeExporter commented 9 years ago 
Good suggestion. I've updated the wiki page:

http://code.google.com/p/jsdoc-toolkit/wiki/TagExample

Original comment by micmath on 11 Feb 2010 at 1:41