Jump to content

API Documentation


gerard1290
 Share

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

 

Link to comment
Share on other sites

Link to comment
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.

 

Link to comment
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!

Link to comment
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.

Link to comment
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.

Link to comment
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.

Link to comment
Share on other sites

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.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

Loading...
 Share

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...