Inconsistencies in jsDoc comments

[ff6347]

While going through the result of the output of documentation.js and comparing it to the comments I found some inconsistencies in the comments we need to fix. For example there are some comments where a return value is an Array of things. Written like this:

* @return {Stories[]} Array of Stories.

In other cases it is just:

* @return {Array} Array of strings

we got some:

/* todo */

Which are (I guess todo for a long time)

There should be an combined effort to review the comments on functions. Maybe by assigning files to contributor. Also we should write down/define how a new function should be documented.

[b-g]

@fabianmoronzirfas happy to help! Should we split the files by 3 or 4 (if @ffd8 is in too)?

This is looks better for me ... but I'm happy to follow any recommendation.

* @return {Stories[]} Array of Stories.

[trych]

I think we also need to decide how the doc should look in the end. This should help us to come up with a consistent version for the inline docs.

From the Skype call, I remember that we want to aim for something close to p5.js. I think a good function to start from is something like b.color(), that has a few different combinations of possible arguments.

I'm super busy the next two weeks, could only look into it afterwards, maybe somebody is willing and has the time to come up with something before that?

[b-g]

@trych Good call! But can we do this as 2nd step and first fix things e.g. missing and wrong parameters etc. And then look into the "text" and examples?

[ff6347]

If we @ffd8 is with us splitting the files into 4 would be good. I think there is no hurry ( @trych ) action needed. I can work with the current state. I just wanted to point that out.

@b-g

This is looks better for me ... but I'm happy to follow any recommendation.

• @return {Stories[]} Array of Stories.

I'm totally fine with whatever we come up with. It just should be consistent.

Another thing that I saw is that we also have sometimes a Collection as return value. This should also be reflected in the statement. Like

* @return {Stories} Collection of Story elements  

Or something like this.

@trych My aim is the following:

index page with all the functions and then a sub page for each function. The subpages need a lot of love. I can generate them but if we want to add further infos we need to write this by hand.

What we can do is automagically include an example script. I can build something that allows to include a file that is next to the index.md and it will be displayed as source code.

The current state is still very rough but can be seen here. It is fully generated. No manual work done yet. https://basiljs.github.io/

[b-g]

👍 + Great!

Just ... what is the difference between a collection and an array? Can/should we not simply always refer to array?

@fabianmoronzirfas Can you as the master of doc simply define the jsDoc style/structure/rules? Might be easier and quicker than to have a long thread on this.

[ff6347]

what is the difference between a collection and an array?

A Collection is an ID own thingy. You can call the everyItem and item and so on functions on it. They don't work on Arrays.

Can you as the master of doc simply define the jsDoc style/structure/rules? Might be easier and quicker than to have a long thread on this.

Yes I can! muahahahahahah!

[trych]

The subpages need a lot of love. I can generate them but if we want to add further infos we need to write this by hand.

Yep, let's try to generate as much as possible, but also allow for additional info.

What we can do is automagically include an example script.

We should differentiate between snippets and example scripts. We should absolutely have a snippet for each function or even multiple if there are several options per function. A link to an example script would also be nice, but should only be an addition. It could be a link to a script sitting in the example scripts directory (which btw. we also wanted to move to a separate repository).

[ff6347]

We should differentiate between snippets and example scripts.

True

It could be a link to a script sitting in the example scripts directory (which btw. we also wanted to move to a separate repository).

Also True

[ffd8]

Hi guys– sorry for delay on this, got pulled into a webapp dev for our school since december and my basil.js love has suffered... nevertheless, great plans above! Sure- happy to join for splitting up the files and going through with fine comb.

Re: Subpages– there is one benefit to having basic text descriptions dumped like it is on the current website, allowing one to do a 'find' across the page for keywords (students use this all the time if not knowing the exact name of function). I wonder if there's a nice compromise that allows the organized reference list first (like we have it), descriptions (as we have it), then an accordion-style expanding snippet and potential isolated function example (when it exists). All staying within the same page, to avoid having to go forward/back/reload all the time? Just reveal/hide on demand.

[ff6347]

Sure- happy to join for splitting up the files and going through with fine comb.

Okay. I will create some issues for that and assign each of us some files to review. Before I will write down some hints what to look for and how a comment should be formatted so we get a good result.

Re: Subpages– there is one benefit to having basic text descriptions dumped like it is on the current website, allowing one to do a 'find' across the page for keywords (students use this all the time if not knowing the exact name of function).

Yes this is what I also do. I was thinking of adding lunar.js to the page to allow a full text search.

I wonder if there's a nice compromise that allows the organized reference list first (like we have it),

Yes I want to create that.

descriptions (as we have it),

This too.

then an accordion-style expanding snippet and potential isolated function example (when it exists). All staying within the same page, to avoid having to go forward/back/reload all the time? Just reveal/hide on demand.

I actually don't want to overload the site with JS features. The site should work without JS (except for the full text search of course) IMHO. Having all the Snippets in there would make the site very large for no script users.

Having the subpage where we repeat the content of the index and go into detail is exactly what Processing & P5.js are doing. I think these references work pretty well.

[ffd8]

The site should work without JS (except for the full text search of course) IMHO.

I'm a jerk and I stopped caring about no-script users (~ 0.25 – 2% of users). I'd imagine if someone's looking into basil.js, they're down with javascript. But true, for a no-script person, all the expanded divs would go on and on..

Yes this is what I also do. I was thinking of adding lunar.js to the page to allow a full text search.

Very nice looking lib and I guess it's main benefit is filtering out (hiding) content that didn't match, vs doing a browser window search/find and it jumping to the highlighted word? Hm and a normal window search probably doesn't find collapsed text, so that lib would be helpful if it went that route.

The other reference pages do work well, was just throwing out the idea if there's a benefit to a single page mighty reference, but maybe not.

[ff6347]

I'm a jerk and I stopped caring about no-script users (…)

I was too (jquery-bootstrapping-light-boxing my live away), but then I just recently came across this post ("Most of the web really sucks if you have a slow connection") by danluu and it made me think. If I would add something like a accordion reveal/hide mechanism I would not code it myself from scratch. This would mean to add in some library (bootstrap?). Then we start adding in jQuery and what not and have one of these bloated sites. So my aim is to have a site that looks good and works well without JS. 😉 It is actually not about the no script users or being a jerk. It's about having a good connection or not. When I look up a reference in 3G on the train or the subway (that happens more often to me than you actually think) I want it to load fast. I also have been in Quito recently. The slow and laggy connections in hotels made it hard to use any of the JS magic sites. Anyway. I could go on and on. I think you get my point.

The other reference pages do work well, was just throwing out the idea if there's a benefit to a single page mighty reference, but maybe not.

Sure. I get it. As you see I thought a lot about it too. The subpages would also allow easier to contribution of tutorials and snippets. Currently they are Markdown only. Contribute a snippet into a jekyll/liquid index.html is really hard if you don't know liquid.

[ff6347]

I wrote some remarks on how to use JSDoc comments in Basil. See the wiki. https://github.com/basiljs/basil.js/wiki/Writing-Documentation

Is something missing?