Is there any tolerance for changing the order and categorization in the property index at the top of each class page? This may also change the order in the remainder of the document as well.
I haven’t assessed the usefulness of this categorization across all Babylon classes.
The first change I would want is to unify Accessors, Methods, and Properties as the difference is usually not relevant to the user.
The other changes below might be more comprehensive (and controversial).
I think the Quick References I’ve posted might be generated by the categorization of properties and changing typedoc generation parameters.
I’ve posted the classes StandardMaterial and Button. I have similar categorizations of Vector3 and Quaternion, not posted.
Of course, I can continue posting in “Tips” with tag “quickreference” until it reaches a critical mass and is worth adoption by the official documentation. Those posts, however, risk being stale at some point. I don’t have a quick way of detecting class changes that would trigger an update.
Challenges:
Consider unifying Accessors, Methods, and Properties as the difference is usually not relevant to the user. (This might be useful even without the other changes?)
Current categorization (Accessors, Methods, Classes, Properties, etc.; or updated per previous bullet) would become the last-level categorization and apply when no other is supplied in source code.
Ability to provide information in horizontal rows may be limited. Example: StandardMaterials.
Utility across all Babylon classes has not been assessed.
Relies on maintenance of categories by developers. Or a developer could rely on the default with zero effort.
I was referring to the docs API Class pages such as this BABYLON.GUI.Button page. The categories would be assigned within the code and generated by typedoc. I am talking about re-ordering the index at the top of the class pages. But maybe there’s a better place to put the resulting categorized index while retaining the existing one?
This is the default typedoc template, we didn’t play around with it too much TBH.
we can see how simple it would be to generate our own template, but i’ll be honest and say that this won’t be a top priority for the time being…
That’s fair. I’ll continue thinking about specific modifications to typedoc configuration. I found tsdoc.json and typedoc-generator.js but don’t see any typedoc.json.
While the differences between Properties and Accessors are not very big, Methods usually have round brackets at the end in order to work properly. So unlifying them all may lead to even bigger confusing for new users, especially of the classic school
Agreed. Maybe just combining the Properties and Accessors, then. When looking for one, a user wouldn’t necessarily know which sectiin to look for it in. Certainly even between Accessors and Properties there are differences in that Accessors can have side effects (additional code in the setter) while Properties don’t (I don’t think).
