search

basiljs / basil.js

An attempt to port the spirit of the Processing visualization language to Adobe Indesign.
http://basiljs.ch/
Other
246 stars 30 forks source link

Remove global constants from listing #317

Closed ff6347 closed 5 years ago

ff6347 commented 5 years ago

Currently all the global constants are not marked as the @subcat constants. That is why they get the () at the end in the reference. Would be good if we would mark them as such https://github.com/basiljs/basil.js/blob/develop/src/includes/constants.js

ff6347 commented 5 years ago

Q: Should we add the @cat global to the constants? Would not make a difference for the docs but would clearer…

trych commented 5 years ago

Wait, wait, wait! So, here's the thing: We discussed this somewhere (will try to find the link if necessary) and I suggested that constants are not listed in the reference except the ones that hold a value that the user can make use of.

So, if there is a constant that is supposed to be only used as an argument in a basil-function, such as CENTER or LEFT or PAGE, then it should not be listed, because this is nothing you would be willing to look up by itself at all in an overview or toc. Rather you only need to find these constants in the descriptions of the functions they belong to, as you only need to find out about them then.

The only constants we should list are those, that do hold an actual value that the user could use in some way, such as PI or LOREM or SCRIPTNAME. Because they don't belong to a specific function, so you would need to be able to look them up in some way.

That's why in the recent restructuring of all the categories, I moved those latter constants with user-relevant values to specific subcategories and left the other ones in the constants file. So all the constants in the constants file should not be listed in the reference.

This is, btw. also how the Processing and p5.js reference handle those constants and I think this is the best way, as this does not add any clutter.

Having said all that, I don't know what that means for a potential @subcat constants. If we could use it to filter those constants from the reference, sure, we could add it. But we might as well introduce a proper ignore tag, if there is such a thing (?). I would let @fabianmoronzirfas decide what is the best way to handle this in the inline docs.

ff6347 commented 5 years ago

Ah okay. I don't remember this. I guess the easiest way is then to remove the blockcomment and use regular comments on the ones that should be excluded

ff6347 commented 5 years ago

I removed the block comments with the latest push on the PR. #318