Jump to content

doc.babylonjs.com v2.0


GameMonetize
 Share

Recommended Posts

Well... as RaananW suggested, there are two doc categories : the user doc (tutos, examples, concepts, primer) and the API doc

The class is definetly a part of the API doc imho. and Even the API could have thematic global entries at a upper level above the class level.

Link to comment
Share on other sites

Hey, menu layouts... I'm easy.  Yeah, the top level menus are not developed at all.  They're just lists of documents in the folder.

 

You bet, those menus can certainly be much better.  I like your format ideas, JC, and sorry for misunderstanding what you were talking about. 

 

If that new layout covers all of our documents, I say install it.  Why not?

 

It would go HERE, right?

 

http://babylondoc.azurewebsites.net/page.php?p=6411

 

Then the 4 subfolders would leave?  The docs in all 4 subfolders... would be raised one level?  Thoughts?

Link to comment
Share on other sites

Hi D72!

 

Your suggestion is for classes?  *nod*.  

 

Sorry about the lack of replies to that.  Your idea is like a classes hotlist in non-table form.  I like it.  We can put it in the same subfolder as the hotlists... maybe call them tree lists.  Maybe I'll rename the hotlists into 'table lists' so their names are more apropos.

 

We/You can use the locations at the top of 2.0 classes and at the top of 1.14 classes, too.  As you can tell, there has not been much development at those 2 locations.  :)

 

 

For the tutorials/wiki, we don't have a document for every class, but we can still build different (and more than one) style of TOC's for the wikis.  This would not require moving any documents, so the subfolder menus won't need updating, and the places in the forum where we gave-out wiki urls... will not go stale.

 

When we move documents, their url's change and thus old links to those documents... fail.  (applies mostly for wikis).

 

For class docs, hopefully, they will never change urls.  But, a new group of urls WILL become active when we generate class docs for new BJS versions.  That's when I make another hotlist and when somebody (you?) makes another tree-like classes list.  :)

 

For our home viewers... don't forget about the great mixed-lists of classes and wikis that you can get... when you use BabylonDocs SEARCH. 

 

Want to see the ULTIMATE documentation list?  Do a search with an empty search field.  Wow, eh?  

 

I managed to steal it.  http://urbanproductions.com/wingy/babylon/docs/alldocs.htm  Now folks can steal it again, from me.  :)   Having this ultimate list nearby when folks create tree-list TOC's... sure makes finding URL's much faster and easier.  Be well, everyone.

Link to comment
Share on other sites

  • 2 weeks later...

Oooh, DK helping me kill a topic.  Cool!  We're partners in this, eh?  :D

 

I think that would make a nice song...

 

Doc on the repo... can't fig your purp.

Why are you there... why do I chirp?

Doesn't he know?  Doesn't he care?

We don't know 'PR', nor do we dare.

Please stay in here, things are more clear... lend us your ear.

 

Ok, they're not the BEST lyrics.... butt hay.  :)

Link to comment
Share on other sites

  • 2 weeks later...

Some news:

 

We will go with a brand new site with content extracted from a github repo. This will work like this:

- All page will be based on a .md inside the repo. For instance, the page /Playpen/Basic Scene will be pulled from $repo/tutorials/playpen/basic scene

- It will be then super easy to edit a page directly on the repo by forking the repo and submitting a PR

- Users rights will be easy to manage thanks to github

- Editing a file could then be done using your favorite md reader (Visual Studio Code, Sublime, etc...)

- You will be able to add pictures directly on the repo :)

- You will be able to PR even for the site design itself

- All the site will be open source meaning that if you want to add a new section/features this will be possible

Link to comment
Share on other sites

Just saw this thread, and looking forward to the new docs :-)

 

For me:

1. Being able to direct link to a function (which should help search engines find stuff).

2a. Direct linking to the source code

2b. Direct linking to playground examples, where available.

3. Guideline: must rephrase function name.

 

I think 1 and 2 are already requested a few times! Number 3, the guidline, means API documentation like this is forbidden:

 

/**

* A widget Material, using alpha.

*/

function widgetMaterialWithAlpha(){}

 

You are not allowed to use any of the words from the function name. Instead you write:

 

/**

* For setting the appearance of a widget when partial transparency is needed.

*/

function widgetMaterialWithAlpha(){}

 

When you cannot do this, you leave the documentation blank; that it was not needed is implied.

(Yes, I know I used the word "widget": we're humans, not robots, so can use common-sense. Here I assumed there was no synonym for widget.)

I've been following this guideline for a couple of years: yes it is harder, and requires more thought for the functions I choose to document, but I also stopped wasting time documenting unambiguously-named functions. E.g. setX() does not need "set the X-coordinate", getWidth() does not need "get the object width", and (to borrow a PHP example), __construct() does not need "A constructor that takes no parameters.". :-)

Link to comment
Share on other sites

+1 for guideline 3.

I agree, I'm always astonished by the general tendancy to not bring any additionnal info in those kind of -useless- function's description.

I'd add a global prerequisite for this rule: above all always use explicit function's and var's names (fortunatly BJS devs and contributors are pretty smart, the source code is quite clear).

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...