search

jsdoc2md / grunt-jsdoc-to-markdown

Markdown API documentation generator
MIT License
16 stars 4 forks source link

Methods show class-prefix (with lowercase character) #1

Closed IjzerenHein closed 10 years ago

IjzerenHein commented 10 years ago

Hi, I updated famous-map to use the latest 'grunt-jsdoc-to-markdown'.

The methods of the class now show the class prefix (with a lowercase character): https://github.com/IjzerenHein/famous-map/blob/master/docs/MapModifier.md

Is this is a bug or intentional? Would it be possible to remove the class-prefix completely, in order to have a shorter notation?

Regards, Hein

75lb commented 10 years ago

hi Hein.. are you sure you have the latest jsdoc2md, because i just generated your docs and MapModifier looks like this (different to your link): https://github.com/75lb/famous-map/blob/master/docs/MapModifier.md

Anyway.. the behaviour is intentional - the lower-case first character is significant, it means the symbol is an instance method..

mapModifier.method - a method of a MapModifier instance MapModifier.method - a class method of MapModifier

without showing mapModifier or MapModifier before the method name i would need to make this distinction another way.. however, i do have the option you requested on my TODO list

here's a class with a mixture of method scopes, to show when it is useful: https://github.com/75lb/jsdoc-to-markdown/blob/master/test/output/commonjs/heaven.md

you can control the instance name by adding a @alias to the @module doclet.. here, the cyberdyne module has an @alias of cyber, resulting in method names like cyber.createMachine().. you could use this technique to get symbols like modifier.positionFrom(position) or m.positionFrom(position) on your own indexes.

it's also useful on indexes for large projects: https://github.com/75lb/jsdoc-to-markdown/blob/master/test/output/all-with-index.md

75lb commented 10 years ago

so, in summary you can get a shorter notation by using an @alias on your @module.. but i will look into the option of removing the class prefix too.

IjzerenHein commented 10 years ago

Hi Lloyd,

I did install the lastest jsdoc2md (globally) and tested with that as well. Then it showed the same output as you are seeing. However when I used the grunt-runner, I got the output from my previous link. I'm guessing the grunt-runner is still using an older version of jsdoc2md ?

I like the idea of distinguishing between instance-methods and class-methods, it had not come to mind with me. You know, then I'dd rather leave it to the default 'mapModifer.', that makes most sense as you mentioned.

When using the latest jsdoc2md, I noticed that my class description is gone. Should I make any changes to the format to get it back?

regards, Hein

75lb commented 10 years ago

sorry, the missing class description was a bug.. it is fixed, this will bring your plugin up to speed: 

npm update grunt-jsdoc-to-markdown

i have learned something new today! i assumed running npm [package] updates all the sub-deps of [package].. but it doesn't, hence why your update of the plug-in did not update the underlying jsdoc2md.. it's caused by this long-standing bug: https://github.com/npm/npm/issues/1341

so, i bumped the grunt plugin version, so now your npm update will work.

IjzerenHein commented 10 years ago

Updated grunt-jsdoc-to-markdown and looking good now!

Thanks again Lloyd!

75lb commented 10 years ago

ok, pleased it looks ok.. will drop you a line one i have the option to remove class prefix (i do agree it is not always relevant or desirable).. plus you'll be able to customise / override any element of the output soon.

IjzerenHein commented 10 years ago

Alright, that sounds great Lloyd, thanks!