Open to documentation change to yuidoc?

[jshirley]

This is a meta-issue, just wondering if you'd be willing to use the yuidoc format. I've wrapped this module in a YUI wrapper, but I'd like to also be able to generate standard documentation.

The format is quite easy and very clean, plus it has really great output.

You can read up on it here: http://yui.github.com/yuidoc/

The change is pretty minimal, and is just in formatting. Here is an example:

/** 
Take markdown (either as a string or as a JsonML tree) and run it through
[[toHTMLTree]] then turn it into a well-formated HTML fragment.

@method toHTML
@static
@param source {String} markdown string to parse
@param dialect {String} dialect to use

**/

If open, please let me know and I'll submit a pull request with the documentation updated and an example YUIDoc page generated (which will be on my gallery module, which you can see at http://j.shirley.im/tech/yui/gallery-markdown/)

Thanks, -Jay

[ashb]

Taking a quick look it seems that the current docs are written in the pdoc style which has the advantage of being markdown - which seems appropriate for a markdown module.

That being said there is nothing currently rendering these docs so they are essentially just free-form comments right now. Having them asa browsable webpage might be useful.

Can you show me a sample of the output for a few of the methods for this module?

[jshirley]

Of course, I haven't finished everything but I fixed up the docs at the top and formatted it in yuidoc format (it's a quick change).

This is the default skin which inherits from the rest of the YUI modules, but is customizable: http://j.shirley.im/tech/yui/gallery-markdown/docs/classes/Markdown.html

Also, yuidoc has full Markdown support as well, which I made usage of to format the synopsis.

Thanks!

On Jun 17, 2012, at 11:27 AM, Ash Berlin wrote:

Taking a quick look it seems that the current docs are written in the pdoc style which has the advantage of being markdown - which seems appropriate for a markdown module.

That being said there is nothing currently rendering these docs so they are essentially just free-form comments right now. Having them asa browsable webpage might be useful.

Can you show me a sample of the output for a few of the methods for this module?

---

Reply to this email directly or view it on GitHub: https://github.com/evilstreak/markdown-js/issues/53#issuecomment-6383437

[ashb]

Can YUIDoc support params of variable types? i.e. the dialect param to parse is either the dialect name (well the key in Markdown.dialects) or a dialect object (with the right methods - we don't check validity of them at the moment, just blindly assume any object is 'correct')

[jshirley]

It's more or less free-form, http://yui.github.com/yuidoc/syntax/index.html#param

What I typically see is something like @param dialect {String | Object} $description (and what I used in some places). The neat thing about @param is that they're nested, so when you have an object you can nest it down (the example in the link above shows that).

On Jun 17, 2012, at 12:00 PM, Ash Berlin wrote:

Can YUIDoc support params of variable types? i.e. the dialect param to parse is either the dialect name (well the key in Markdown.dialects) or a dialect object (with the right methods - we don't check validity of them at the moment, just blindly assume any object is 'correct')

---

Reply to this email directly or view it on GitHub: https://github.com/evilstreak/markdown-js/issues/53#issuecomment-6383722

[jshirley]

By the way, it sounds like you are at least interested.

Shall I fork and submit a pull request with the documentation formatting changes? Then we can comment on actual code :)

On Jun 17, 2012, at 12:00 PM, Ash Berlin wrote:

Can YUIDoc support params of variable types? i.e. the dialect param to parse is either the dialect name (well the key in Markdown.dialects) or a dialect object (with the right methods - we don't check validity of them at the moment, just blindly assume any object is 'correct')

---

Reply to this email directly or view it on GitHub: https://github.com/evilstreak/markdown-js/issues/53#issuecomment-6383722

[ashb]

Sure go for it.

Its a little bit javadoc for my linking but that's just my old hangup against Java.