Closed azaslavsky closed 9 years ago
75lb
commented
9 years ago i can't reproduce this.. this code works correctly for me (with the ignored var not present in the output)..
/**
a visible global
*/
var visible = true;
/**
an ignored global
@ignore
*/
var invisible = true;can you send an example of an @ignore tag failing?
azaslavsky
commented
9 years ago Yeah. I'm about to push some commits on a repo I'm working on, I'll link it when I do.
azaslavsky
commented
9 years ago So, head over to backbone.hashMate's repository and do a dev install on NPM. If you run gulp api, it should use gulp-jsdoc-to-markdown in the task. The output will be visible in docs/API.md. In my attempts, Backbone.History.prototype.checkUrl is still visible in the API output, even though it has been marked with an @ignore tag.
75lb
commented
9 years ago fixed in jsdoc-parse.. run npm update in your project then try gulp api again.. thanks for report :+1:
azaslavsky
commented
9 years ago You the man (or woman)! Thanks for the super quick turnaround. :+1:
75lb
commented
9 years ago lolz! I'm Lloyd Brookes, a male full-stack javascript fan based in London.. just to de-mystify myself a little ;)
PS. i'm almost ready for alpha-testing on jsdoc2md@next, will give you a shout soon about that..
azaslavsky
commented
9 years ago Yeah, love the library, happy to contribute.
75lb
commented
9 years ago quick preview of the new format https://github.com/75lb/backbone-hashMate/blob/master/docs/API.md
azaslavsky
commented
9 years ago Oh wow, the table format is so much easier to read. Also appreciate you adding support for parameters that are more than one level deep in an object dictionary (ex: opts.deleteHash.groups is on the same indentation level as opts.deleteHash and written in a confusing way in the previous version, as seen here). Excited for the release!
azaslavsky
commented
9 years ago Hmm, I very strongly prefer the look and feel of the new layout. What would I have to do to start using it now? Is there any chance you could make a pre-release of the gulp-jsdoc-to-markdown plugin, something like 0.1.6-alpha1? Would love to give it a whirl.
75lb
commented
9 years ago hi :)
ok.. run npm install -g jsdoc-to-markdown@next but i am still working on it - use at own risk ;)
see jsdoc2md --help for latest options (which will change soon)
75lb
commented
9 years ago one little tip, if you want your @examples to be automatically syntax-highlighted as js, use
$ jsdoc2md --example-code-gfm js lib/source.js
these options will change, but this is the current state
azaslavsky
commented
9 years ago Found another bug in 0.6.2: when a @param (though probably any tag that accepts variable types), has several possible types specified (ex: @param {boolean|string|number} someName), each type gets its own column, rather than being listed as type1|type2|...|typeN in a single column. This is probably due to a confusion of the gfm table row syntax with the jsDoc variable type syntax.
An example (scroll to history.navigate):
75lb
commented
9 years ago this could be an issue with this particular markdown editor - that same markdown works fine on github https://github.com/75lb/backbone-hashMate/blob/master/docs/API.md
75lb
commented
9 years ago you can paste the table directly into these comments and it looks fine
| Param | Type | Description | |
|---|---|---|---|
| [fragment] | string |
The new fragment | |
| [opts] | Object |
An extended version of the default options object, with the following properties available | |
| [opts.deleteHash=false] | boolean |
Object |
True means we reset the entire hash, false means that nothing is cleared |
| [opts.deleteHash.globals=false] | boolean |
Array.<string> |
Setting true will clear all global variables, or an array can be specified for more granular deletion |
| [opts.deleteHash.groups=false] | boolean |
Array.<string> |
Setting true will clear all prefixed variables, or an array can be specified for more granular deletion |
| [opts.addHash] | string |
Object |
Either an encoded string or a key->value dictionary of hash parameters to be changed along with the fragment; this will be applied after the "clear" variables are processed |
| [opts.forceTrigger=false] | boolean |
True forces a triggered URL to load, even if the URL matches the current one; only used it "opts.trigger" is also true | |
| [opts.replace=false] | boolean |
Works exactly like the default "navigate" implementation, see http://backbonejs.org/#Router-navigate | |
| [opts.trigger=false] | boolean |
Works exactly like the default "navigate" implementation, see http://backbonejs.org/#Router-navigate |
azaslavsky
commented
9 years ago You're totally right - it was the previewer that was the problem, not your code. Oops!
Either way, I'm now using the pre-release build for the library's documentation to excellent effect! Thanks!
Currently, adding the
@ignoretag to a jsDoc block has no effect. It would be nice if ignore tags did exactly what it says on the tin.