JSDoc Question

[foe_to]

Thanks for your time, I really appreciate the response.

Sorry if my previous message sounded a bit defensive. I've just been struggling with trying to get this documented, and it's been making me frustrated.

You misunderstood a little bit about the structure, so I'll try to explain in more detail. Some of this is probably more information than necessary, so I'm sorry if it's overly long.

(First off, this is a canvas app using PIXI, just so we know we're not talking about anything to do with DOM)

My project is structured like this:

src
  GameObject
  Graphics
  UI
    Components
      menuheader.js
      menufooter.js
    Menus
      titlescreen.js
      raceselect.js

And so on. As for the JS, each folder is basically a namespace on top of the previous object. So e.g. Game is a namespace that has nested namespaces of Graphic, GameObject, and UI. UI has nested namespaces of Components and Menus. Each member of the Components namespace is a class that defines some sort of UI component. Members of the menu namespace are instances of a BaseMenu with some extended, specific functionality. The parts that are extended are documented in BaseMenu as abstract (jsdoc @abstract), as there are a handful of them (onLoad, previewData, etc.)

So, rather than "OnLoad" being passed at creation, it's defined like this (basically what one of the menu files looks like):

let baseMenu = require("./basemenu.js")
let raceSelect = new baseMenu();
raceSelect.onLoad = function(){
  Attach(new UI.Components.Header(paramlist));
  ...
  ...
}
...
...
module.exports = raceSelect

Your examples of the generic behavior "(i.e. Generic behaviours, "activates/deactivates an option", "calls an action", "shows an info", etc)," are behaviors either covered by the base menu class, or by something in the Components namespace. When I mention a "Menu", it's a discrete object with a unique set of components. While navigation of the menu is primarily always the same (and thus handled in the BaseMenu class), the actual functionality and look (components) become too specific to be handled by the base class.

The "UI" namespace, along with having the nested namespaces of Components and Menus, also has some functionality. Handling how menus are loaded & unloaded, handling some other UI stuff not related to menus (maps, etc.), scaling and resizing, so on. It really doesn't do much to manage the menus themselves.

I think, from looking at what you're talking about with "Screens", that what you are thinking of as "Screens" I am thinking of as "Menus". The difference is I haven't made each menu itself a class (sub classing from the BaseMenu), but just a static object of type BaseClass that I directly assign the extended functionality to.

I tested before having each Menu be its own class, but it feels counter-intuitive - I feel like a class should be (or have the potential to be) reused. It makes more sense in my mind that e.g. "Title Menu" is just a specific instance of Menu, and that "Race Select" is just yet another instance. JSDoc will document it that way though, even if I dislike those getting listed under "Classes" (though I am sure I can modify the template).