Add `groupGlobalsBy()` helper function

[zanerock]

In order to support a grouping globals by category, let's add a groupGlobalsBy(groupByFields, options) function. Currently, you can only really group by category if the grouped identifiers are part of a module (because the groupBy() works explicitly with child identifiers so there must be a parent involved). Adding groupGlobalsBy() will allow global identifiers to be grouped by category as well.

[75lb]

Grouping by category is already possible.. See this folder in the testbed - have a look at the example source in 0-src.js and the output in 3-dmd.md.. Have a play and let me know what you think..

[zanerock]

Thanks for the feedback. I had seen that was possible, but (I think) the items have to be in a module for that to work because the group by function requires the items to be the child of something. I could not see a way to group the global identifiers, hence the new function.

In my specific use case, I don't really want or need the module designation. I did try to use it just to get the grouping working, but I ran into issues. If I remember correctly, the problem was the identifiers were spread across multiple files and that was causing problems in the output. But, ultimately that was just a workaround and I'd strongly prefer to keep the identifiers in the global space for my purposes.

[75lb]

Will take a deeper look.. It could still make V9 which is still in beta..

[75lb]

Was your issue partly due to the fact you were unable to modify a built-in helper (e.g. inlineLinks) similar to this report #91 ?

[75lb]

Nevermind, I closed the issue I just mentioned (#91) as I couldn't reproduce the issue - it is possible to override system helpers and partials.

I think you could implement groupGlobalsBy via a custom helper.. Put this in a file:

const overrides = {
  // a system helper
  inlineLinks: function (text, options) {
    // the original code plus your modifications
  },

  // your custom helper
  groupGlobalsBy: function () {
    // your thing
  }
}

module.exports = overrides

then run jsdoc2md passing in your helper file, plus any custom partial files that reference your new helpers..

$ jsdoc2md --helper custom-helpers.js --partial custom-partial.hbs --files *.js

Let me know if that solves your issue..

[75lb]

Btw, you might want to test the solution i just suggested using jsdoc-to-markdown@next, which is soon to go live..

[zanerock]

I'm aware of being able to override/add helpers. My issue was more about being able to access the root dmd helpers. E.g., groupGlobalsBy() uses _groupBy and _globals. You can access those from the partials, but I don't see how I could access those from my own helper function. So to implement groupGlobalsBy(), I would have to also copy/implement _groupBy and _globals, which is possible but a bit clunky.

[75lb]

thanks for clarifying, that helped.. Could you send a link to a project where groupGlobalsBy() is currently used? I want to try something and, if it works, i'll send you a patch..

[zanerock]

I've got two:

• regex-repo : Sorts by category; hides the 'class/function/type...' grouping because there's only one type.
• standard-error-set : Same thing, but has both Classes and Functions so just shows another layer of grouping (still uses groupGlobalsBy()).

These are generated using dmd-readme-api (and a patched version of dmd, @liquid-labs/dmd, which adds the groupGlobalsBy() function). The relevant partials in dmd-readme-api are in the main.hbs, where it calls the dmd-readme-api helper sortAll() and then the global-index-grouped.hbs where it invokes the groupGlobalsBy().

I'm not certain if sortAll() (from my dmd-readme-api plugin) is actually necessary. I had it there originally because I was getting separated groups in the doc. I don't remember exactly, but it was something like I'd get a class, then a function, then a class again. I believe this may be related to my having the module / global definitions spread across multiple files. So I just sort everything first. I don't remember if groupGlobalsBy() ends up sorting or not itself.

[75lb]

Thanks, will come in useful.. I made a start unpicking the handlebars hellzone within dmd over the weekend, massively slowed down by issues in the dep tree (this time it's handlebars, usually it's jsdoc). Anyway, will add your plugin to my testbed and try a few things, thanks..

Btw, yes the helper methods you mentioned need factoring out of the project (again) so they can be reused elsewhere - that's the general focus of what i've been working on.. again.. (I won't bore you with the details but ddata used to be an independent module for reuse by dhtml, dterm and other templates which existed back in 2015/16, before being abandoned, along with two additional jsdoc2md rewrites, due to still-outstanding jsdoc issues upstream)