jerome Posted May 13, 2015 Share Posted May 13, 2015 Well... as RaananW suggested, there are two doc categories : the user doc (tutos, examples, concepts, primer) and the API docThe 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. Quote Link to comment Share on other sites More sharing options...
Temechon Posted May 13, 2015 Share Posted May 13, 2015 It can be done, but the thematic relation has to be managed manually. It's not a problem though. Quote Link to comment Share on other sites More sharing options...
jerome Posted May 13, 2015 Share Posted May 13, 2015 YepIt's a manual process... but done once only : this class in this theme Temechon 1 Quote Link to comment Share on other sites More sharing options...
Wingnut Posted May 13, 2015 Share Posted May 13, 2015 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? Quote Link to comment Share on other sites More sharing options...
Wingnut Posted May 15, 2015 Share Posted May 15, 2015 Ain't I great at killing threads? I'm SO proud. sigh. jerome 1 Quote Link to comment Share on other sites More sharing options...
Dad72 Posted May 15, 2015 Share Posted May 15, 2015 In made, I had already made suggestions to improve/relook this part of documentations, but nobody had reacted. here:http://babylonjs.uservoice.com/forums/267546-general/suggestions/6993007-grouped-node-thematically-doc-site Quote Link to comment Share on other sites More sharing options...
Wingnut Posted May 15, 2015 Share Posted May 15, 2015 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. Quote Link to comment Share on other sites More sharing options...
GameMonetize Posted May 15, 2015 Author Share Posted May 15, 2015 To be actionable, this have to be explained in the doc on the repo. We will use this doc as specification for next documentation site Quote Link to comment Share on other sites More sharing options...
Wingnut Posted May 26, 2015 Share Posted May 26, 2015 Oooh, DK helping me kill a topic. Cool! We're partners in this, eh? 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. Quote Link to comment Share on other sites More sharing options...
GameMonetize Posted June 4, 2015 Author Share Posted June 4, 2015 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 Dad72, Vousk-prod. and jerome 3 Quote Link to comment Share on other sites More sharing options...
Vousk-prod. Posted June 4, 2015 Share Posted June 4, 2015 I love this idea! Dad72 1 Quote Link to comment Share on other sites More sharing options...
qqdarren Posted June 6, 2015 Share Posted June 6, 2015 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 code2b. 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.". :-) Dad72 1 Quote Link to comment Share on other sites More sharing options...
Vousk-prod. Posted June 6, 2015 Share Posted June 6, 2015 +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). qqdarren 1 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.