search

miyo-jp / jsdoc-toolkit

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

Patch: Add 'wiki' style formatting to descriptions #86

Open GoogleCodeExporter opened 8 years ago

GoogleCodeExporter commented 8 years ago 
The attached patch allows text in the documentation description to be 
processed by a tiny wiki engine.  
The benefit is that text can be written in a more natural/readable format, 
but still benefit from the styling of HTML.

The formatting follows the basics of the wiki for this project and 
provides the following formatting.

 * A 'gap' line will generate a new paragraph, keeping the distinction 
between text blocks.
 * *bold* - text surrounded by * will be shown as bold
 * _italic_ - text surrounded by _ will be shown as italic
 * `code` - text surrounded by ` will be shown as code
 * ^superscript^ - text surrounded by ^ will be shown as superscript
 * ,,subscript,, - text surrounded by ,, will be shown as subscript
 * lists - Two spaces followed by a * will create an un-ordered list entry
 * lists - Two spaces followed by a # will create an ordered list entry

Hope you like it...

Darren

Original issue reported on code.google.com by darren.t...@googlemail.com on 23 Feb 2008 at 7:54

Attachments:

GoogleCodeExporter commented 8 years ago 
Hi Darren,

This topic was hotly discussed once upon, here:
http://groups.google.com/group/jsdoc-2/browse_thread/thread/d4d4f4dbaaa36ac7/2c9
2316c80a5fbda?lnk=gst&q=markdown#2c92316c80a5fbda

If you read the start of that thread, you'll see I was the one who proposed a
markdown format for descriptions in comments. The general consensus was to 
stick to
HTML. I think I ended that thread by saying I'd like to see some add-ons that 
would
allow people to choose whatever formatting language they wanted. I, of course, 
never
had time to implemement that, which is why I'm glad to see your patch.

However, now that Version 2 will have plugins, I'd rather see this implemented 
that
way, and people can choose to use it or not.

Original comment by micmath on 23 Feb 2008 at 9:17

GoogleCodeExporter commented 8 years ago 
Im fine doing it via a plugin, if that will be the preferred method, but 
looking at 
the plugin architecture, there are only a few plugin calls defined.  

How do suggest this is best implemented? Would I need to find my own trigger 
point 
and define a new plugin 'event' ie onPublishDesc?

What plans do you have of defining/creating these triggers to hook the plugins 
too?

If this is not the place, I can start a thread on the main group

Original comment by darren.t...@googlemail.com on 24 Feb 2008 at 6:52

GoogleCodeExporter commented 8 years ago 
I was assuming your plugin would do its work like commentSrcJson, using
onDocCommentSrc, or perhaps onDocCommentTags could be used. If you need a more
specific hook, just request it and I'll set you up.

Original comment by micmath on 25 Feb 2008 at 6:34

GoogleCodeExporter commented 8 years ago 
Attached is the same patch but in plugin format.

It fires on the onDocCommentTags hook, and processes the 'desc' field(s).   One 
side 
effect is having multiple '@desc' tags.  Each one will be treated indepently 
and 
wrapped in <p> html tags.

Couldn't find any info on the wiki as to where to put plugins, so for now its 
here.

Darren

Original comment by darren.t...@googlemail.com on 25 Feb 2008 at 1:54

Attachments:

GoogleCodeExporter commented 8 years ago 
I will look at this and add it to a plugin gallery (yet to be created) before or
shortly after Version 2 final is released. many thanks for this.

Original comment by micmath on 5 Apr 2008 at 8:36

GoogleCodeExporter commented 8 years ago 
Just wanted to let you know that I've written a plugin to use markdown in @desc 
tags. You need the showdown library for this to work.

Original comment by a...@geekosphere.org on 20 Feb 2011 at 8:18

Attachments:

GoogleCodeExporter commented 8 years ago 
I think the markdown should be applied on parameter descriptions too (and 
anywhere else there is significant text - is there anywhere?)

I've attached a version of the plugin that adds the conversion of markdown in 
params, and I've also updated some of the instructions in the comment.

Original comment by phas...@gmail.com on 11 Dec 2012 at 10:18

Attachments:

GoogleCodeExporter commented 8 years ago 
I've revised that and added @class and @see as well (attached)

Original comment by phas...@gmail.com on 12 Dec 2012 at 2:02

Attachments: