marcuslucero / jsdoc-toolkit

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

{@code} inline tag #274

Open GoogleCodeExporter opened 9 years ago

GoogleCodeExporter commented 9 years ago
We use the following to allow {@code} inline tags in our doc comments,
instead of the more verbose <code></code> markup.

   str = str.replace(/\{@code ([^}]+)\}/gi,
      function(match, code) {
         return '<code>' + code + '</code>';
      }
   );

As far as I can tell there is not support for inline tags, so the above
code is in our publish.js resolveLinks function.  Given our usage,
resolveLinks is a misnomer, something like
[resolve|handle|process]InlineTags is more accurate.

Original issue reported on code.google.com by ryan.gus...@gmail.com on 30 Dec 2009 at 5:00

GoogleCodeExporter commented 9 years ago
What happens if there is a closing curly brace in the code?
Like:
{@code obj={a:1}}

Original comment by micmath on 31 Dec 2009 at 12:19

GoogleCodeExporter commented 9 years ago
Even in JavaDoc, there is no } escape syntax for inline tags of which I know.  
It's
not in the documentation I've read on the JavaDoc format, although 
implementation may
differ I guess.  I assume it cannot be used for such code snippets in the desire
fashion.  I believe it would match in the first } encountered, with the 
remaining }
being outside the inline tag, and thus treated as doc.

We mostly use it for {@code null}, instead of <code>null</code>, and other such 
short
snippets (true, false, numeric literals, paramater names, etc).  It's not an 
issue
for us.  For large multi-line code blocks, it makes more sense to use 
<code>/<pre>
style documenting.

We're not doing the HTML escaping stuff that happens in JavaDoc either.

FYR: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@code}

After I wrote the above, I google'd this up, which would seems to agree: 
http://stackoverflow.com/questions/647195/how-do-you-escape-curly-braces-in-java
doc-inline-tags-such-as-the-code-tag

Original comment by ryan.gus...@gmail.com on 31 Dec 2009 at 12:50