Recommended Posts

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,

image.thumb.png.d7bfa23500c31c1fa7257d0845af6277.png

 

Share this post


Link to post
Share on other sites

Share this post


Link to post
Share on other sites

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.

 

Share this post


Link to post
Share on other sites

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!

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.