Open RealCrayfish opened 3 months ago
RealCrayfish
commented
3 months ago Some examples of how it could be layed out:
https://doc.rust-lang.org/std/ https://docs.unity3d.com/560/Documentation/ScriptReference/index.html https://docs.python.org/3/c-api/index.html
And of course not everything needs an in-depth description as long as people can find the methods and properties available in the engine.
optimo
commented
3 months ago Nez docs are a thoughtful taste of what is included. Nez being 100% open source puts it in contrast to a lot of other game engines. Devs are encouraged to look at the comments present in most nez classes, and many of the properties and methods have documenting markup that typical IDEs can show hints from, or used for automatic generation of docs/api info.
Not to discourage your idea; after spending some fair time with Nez, one realizes the engine is not that big or intimidating unlike some (it being 2d focused is part of why it can be uncomplicated), and discovering its features is a bit of fun. The faq/md files seem geared towards helping you out with whatever task you're working on. The separate Nez-Samples repo is also very helpful for starting out, giving just a taste of what is possible while not being too authoritative - nez is lightly opinionated but does not require you to do things a certain way, accommodating different styles of organizing your project.
The samples show some of the quickest ways to setup a scene, for example, but one may choose to get more complicated using entity subclasses as a sort-of prefab-like container; adding factories, managers, etc. Nez is great for new devs that are clueless, and also for those experienced devs that know exactly what they have in mind.
If one wants a static api documentation a lot of that can be generated from the code comments - it has a lot of well-commented modules. Having all the source code at-hand and mostly marked-up is really valuable. The engine sort-of expects that you know what you want and a rough idea how to do it, and it mostly about convenience and time-saving. There's a handful of us active on the discord, btw if you're looking for a little support chat. I'll be happy to try and help out.
You could take a crack at generating the docs from the comments. It just seems like an extra step when I can get the same from looking at the classes and hints in vscode/vstudio. Why look at two versions of essentially the same information when we can go right to the source. For classes that might a little thin on code-comments, I'm sure prime welcomes pull-requests to improve those parts. Contributions are appreciated in any case. I suppose if an explicit api docs were in demand, they would have materialized by now after several years. The lack of such things is certainly not an impediment to newcomers deciding whether to adopt the engine for their projects.
There may be some shock for newcomers accustomed to docs like in your links; some 'reference manual' type docs are a secondary effort that probably seems unnecessary once you've dug in a bit and use it in practice. Nez is a framework moreso than a game engine; a collection of very helpful conveniences. The unity-like component-first way of building a project - which is also optional - is the conceptual engine at work. That much is understood from the existing faqs, as an ice-breaker. I think devs choosing to use nez probably are at least that familiar with the concept.
As far as I know, there doesn't seem to be any API reference available for the engine. Since not every single method or property is documented in the docs it may be preferable to create one.