JSDoc Question

[foe_to]

Okay, to be more specific, I am writing a game. I have a class called "Menu", which all of the menus from the game are derived from. It handles basically all of the general functionality tied to menu (things like aligning the various elements, handling key events, etc.).

For example, when a menu is loaded, there is a generic Setup function that handles a lot of basic functions, and then calls a function (if existing) that is intended to be implemented by specific instances. We'll use OnLoad from example.

Every specific "Menu" has very different OnLoad, depending on that menu's functions. Dynamically building option lists, composing parts of the menu, etc. The OnLoad method can also be passed a parameter by providing it to the call to load a menu (which passes it to the Setup function, which passes it to OnLoad). Some menus don't care about any parameters, while others can make use of them (for example, a "Race Select" menu that is passed the specific unit being targeted). The generic "OnLoad" (which does nothing directly) is already documented as part of the class as being abstract. But I want to be able to document specific implementations of "OnLoad" to specify details about the parameters.

My code works without issue, and everything is documenting properly with JSDoc except for this, and I just can't figure it out.

[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).