gerard1290 Posted March 13, 2018 Share Posted March 13, 2018 Hello Forum Members, I am starting development using BabylonJS Engine and just wanted to see where is the best place to get understanding the use of the engines api's? I find the documentation section of the official site quite lacking(see image). I have been googling for 4 hours and can't find reasonable examples of how I should be using the api's . I have started watching the 8 hour video series, but wanted to see if there is a good source for referring back to during development. Let me know if I am missing something here? Thanks, Quote Link to comment Share on other sites More sharing options...
adam Posted March 13, 2018 Share Posted March 13, 2018 Use the search feature at https://doc.babylonjs.com/ https://doc.babylonjs.com/search?q=dynamic+texture https://doc.babylonjs.com/extensions/dynamic_terrain Edit: I just realized that last link is dynamic terrain not dynamic texture You can also use the PG search: https://doc.babylonjs.com/playground?code=dynamictexture https://www.babylonjs-playground.com/#1282WV#14 Wingnut 1 Quote Link to comment Share on other sites More sharing options...
Guest Posted March 13, 2018 Share Posted March 13, 2018 And yeah, our next improvement is to work on class API documentation. We need time for that and help from the community Quote Link to comment Share on other sites More sharing options...
gerard1290 Posted March 15, 2018 Author Share Posted March 15, 2018 Thank you for the replies, Adam, thanks for putting together a list for me, much appreciated! I completely understand where the Babylon.js developers are coming from(Improved documentation is of my objectives at work as well), but I think proper documentation should not be sidelined as it will likely increase adoption and help grow the community. I am down to help as I learn. Quote Link to comment Share on other sites More sharing options...
Wingnut Posted March 15, 2018 Share Posted March 15, 2018 Hi guys. Gerard... welcome to the forum, and your docs attitude is wonderful. BJS is international. Would "proper documentation" include doing it in multiple languages? Point: There is a limit to English words. In the spirit of "A picture is worth a thousand words"... somebody modified it into "A demo scene is worth a thousand words"... and that is why one of our primary docs heroes... invented PBT's... playground-based tutorials. The feature/system hasn't been used very much, yet... but the hope is that PBT's would remove some of the "overwhelm" caused by too many (English) words. Everyone is still thinking about it all, yet... especially @JohnK. He's a miracle worker, really. A super-teacher. Great coder and geometry guy, too. He did the first demo PBT and built a tasty feature-set to assist in their writing/coding. So... what do you think, Gerard? Do you think teach-by-demo has more traction than teach-by-words? Do you think that tutorials... that happen inside a playground scene... help promote immediate experimentation by the user doing the research? (they can immediately and easily start "hacking" the code and seeing what it does.) Do you have to deal-with internationalization (i18n) in your docs job? We'll take ANY comments you have... about these things. (thx!) We're still learning about documenting fast-moving things... 'round these parts. We sometimes talk about docs... in an un-pinned forever-thread called Tutorial Talk. Use it anytime... it's a good place to discuss docs stuff. Party on! Quote Link to comment Share on other sites More sharing options...
Wingnut Posted March 18, 2018 Share Posted March 18, 2018 Thread killer Wingnut... scores another kill. JackFalcon 1 Quote Link to comment Share on other sites More sharing options...
gerard1290 Posted March 19, 2018 Author Share Posted March 19, 2018 Hi Wingnut, Sorry for the late reply. Glad to hear your take on this. I completely agree that the playground is a valuable source to learn and try out bits of code, but I think documenting the api's would still be beneficial for reference (parameter descriptions, option descriptions, optimal use cases). Also searching through the forum is time consuming work to find the example that applies to your use case. As far as examples, I think a playground link on the api page is the way to go as it would be easy to find and give users the ability to expand on the code. This code should be line by line commented to explain exactly what is going on which is something I rarely find in the examples. Wingnut 1 Quote Link to comment Share on other sites More sharing options...
Dad72 Posted March 19, 2018 Share Posted March 19, 2018 I've been talking about this for a long time that the class documentation should have some small examples of using the functions and maybe some properties. One can like the docs of Unity (I also like the doc of PHP which is very community). I think if we had documentation like that, it would help a lot. Myself when I go in the doc I do not really know what I'm looking for sometimes and the functions that I see just tell me their signature, see a small description, but not in what case the used with concrete example or link to the playground for example. Maybe it would take a document that can be edited easily to add pieces of code to explain the functions as and when. It would also be useful to have links with 'See also' in functions when there is another function relevant to the one we are looking for. For example Vector3 => see also Vector2 ... It is a very big work to realize but will make the documentation more informative. Just ideas. Wingnut 1 Quote Link to comment Share on other sites More sharing options...
JohnK Posted March 20, 2018 Share Posted March 20, 2018 9 hours ago, Dad72 said: It is a very big work to realize You are correct and I wish I had the knowledge and skills to improve the API and make some of the features suggested available. As far as I understand it the API class documentation is generated from the Babylon typescript files directly. This makes sense as then any updates to any classes would result in changes in the API. The first problem is that this works well when the typescript file has appropriate comments but many older files need these comments added and help is needed there. Somebody, outside the core team, was working on improving the 'build' engine that generated the API documentation however like all open source programs work and life get in the way and projects get dropped, or paused for a long time, without being finished. Nobody is at fault it is just the nature of open source. There is a github where this was started so anyone with the skill and inclination could communicate with the author and Deltakosh to help continue the work. Secondly to incorporate PGs into the API the 'build' engine would need additional code and somebody would need not only to write that code but people would be needed to write or find appropriate PGs to link to. Anyone is welcome to volunteer for this. Quote Link to comment Share on other sites More sharing options...
Guest Posted March 20, 2018 Share Posted March 20, 2018 I asked @RaananW to work on the API documentation generation tool and he kindly accepted We will soon have a better API documnetation If anyone wants to help, please just add typedoc comments to any uncommented function We are also enforcing any new PR to come with commented code Dad72, gerard1290 and RaananW 1 2 Quote Link to comment Share on other sites More sharing options...
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.