Sort by name

[whitlockjc]

Thanks for your work on this project. One thing I'm missing is I'd like to be able to sort things by name. Right now, the order in which the members are defined is the order they're displayed in. I'd like to be able to sort things by name alphabetically for example. Any way to do this?

[75lb]

well, there's a --sort-by option on jsdoc-parse: https://github.com/jsdoc2md/jsdoc-parse#parseoptionssort-by--array

does that help? try sorting by "kind" then "name".. or whatever combination works.. let me know if you get what you need..

jsdoc2md v2 will be a vast improvement, work started recently..

[whitlockjc]

I found the sort-by option, I'm using this programmatically, but when I use name in the array, it doesn't seem to help. Here is the sources:

gulp.task('docs', function () {
  return gulp.src([
    './index.js'
  ])
    .pipe($.concat('API.md'))
    .pipe($.jsdoc2MD({'sort-by': ['scope', 'kind', 'name']}))
    .pipe(gulp.dest('docs'));
});

I've also tried just ['name'] and ['kind', 'name'] and they all produce the same sorting for the kind that appears to be based on definition order and has nothing to do with name-based ordering.

[whitlockjc]

That's the reason I asked, I've tried a few different variations of the sort-by option for this. Maybe it's because I'm doing this with gulp-jsdoc-to-markdown?

[whitlockjc]

In case you want to see it, attached is a screenshot when attempting to sort by name.

[whitlockjc]

Notice how findRefs is at the bottom? The order is as defined in my index.js and attempting to sort by name does not change this.

[75lb]

i did a quick test and it worked as expected.. see output: https://gist.github.com/75lb/9e33f486d75f299e3b95

checking the gulp plugin now.. hmmm, i fear a npm issue..

[75lb]

i couldn't reproduce the issue using gulp.. see my output: https://gist.github.com/75lb/348417b59a5f9548a5cb

which version of npm are you using? can you point me to some failing source code to test with?

[whitlockjc]

Thanks for putting in the time. I'll try again and see what comes of it. When I push these changes, I'll point you to it as well. Feel free to ping me if you've not heard from me in a few days, I'll be out of town.

[whitlockjc]

I can confirm that {'sort-by': 'name'} works. Maybe the issue was with how I was doing it. That being said, let me ask you a question: If sort-by is an array, what is the intended function?

[75lb]

the syntax is --sort-by <list of property names>.. for example, the default is --sort-by scope category kind order which means sort by scope then category then kind then order..

the intended function is to give the user full control over what order the docs are rendered in.. it's not massively useful.. version 2 will do it a lot better.

[whitlockjc]

It seems to be working now. I've no idea what was up. Just using name or ['scope', 'category', 'kind', 'name'] is working but the latter wasn't when I reported this. I'll close this as it seems to be working. Thanks for your time.

[75lb]

strange.. oh well, glad it's working.. don't be shy to report anything else you find.. i created a jsdoc2d gitter room too, if that helps..