Documentation Update

[matthewkaney]

Doing a pass at adding some more undocumented functions and eventually adding more type annotations, etc. For now, just focusing on straightforward documentation tasks (though please leave comments or commit to this branch if you have any edits!), but I also have a couple other things in mind that would be good to discuss:

1. How do we want to approach type annotations for patternified parameters? I'd like to start using template parameters (like Pattern<number> or Pattern<X> etc), but would that be an acceptable replacement for number | Pattern? I think so, but could be convinced if we really want to emphasize that primitive values are acceptable and will be automatically reified.
2. Another thing I'd like to do is separately specify both valid method signatures, something like:

   Usage:
   `pattern.fast(factor)`
   `fast(factor, pattern)`
   

   For most registered functions, we wouldn't need to hand-write this, you could just have a tag that tells an extension to auto-generate this from the set of params, but it would be nice to allow a specific @signature tag in cases (such as stack or especially layer) where the two usages are distinct. This would require a new jsdoc extension, but I don't think it's very complicated.
3. I'd also like to add explicit types for functions passed as parameters. Do you all have a preference between the Closure Compiler style (@param {function(Hap):boolean}) versus the Typescript style (@param {(hap: Hap) => boolean})? I prefer Typescript but don't mind the Closure style either. Both work in VS Code's jsdoc parser and unfortunately neither is actually supported by the jsdoc library, so we'd need an extension in either case.
4. Also, any objections to documenting all of the external Pattern methods maybe with an @internal tag that disables autocomplete and maybe also hides them from the reference until we can improve the reference UI?

[felixroos]

1. How do we want to approach type annotations for patternified parameters? I'd like to start using template parameters (like Pattern<number> or Pattern<X> etc), but would that be an acceptable replacement for number | Pattern? I think so, but could be convinced if we really want to emphasize that primitive values are acceptable and will be automatically reified.

the fact that everything can always be a Pattern (with very few exceptions, like pianoroll), means we could possible omit Pattern<> entirely and only specify the type of the hap.value. if that's too unorthodox, i'd also prefer Pattern<number> over Pattern | number

2. Another thing I'd like to do is separately specify both valid method signatures, something like: pattern.fast(factor) fast(factor, pattern)

also not sure about this. even though the function and the method are technically 2 things, they are conceptually the same from a language perspective. i think using the function directly is a very narrow use case, mostly practical for library users. i'm a bit worried that this might clutter the docs with info that is not useful for the majority of users.

maybe we need some way of separating docs for library users (technically accurate, less accessible) and repl users (technically less accurate, more accessible)? alternatively, we might need a page that talks about all the "conventions", like "all functions always accept patterns" and "all methods exist as top-level functions as well".

3. I'd also like to add explicit types for functions passed as parameters. Do you all have a preference between the Closure Compiler style (@param {function(Hap):boolean}) versus the Typescript style (@param {(hap: Hap) => boolean})? I prefer Typescript but don't mind the Closure style either. Both work in VS Code's jsdoc parser and unfortunately neither is actually supported by the jsdoc library, so we'd need an extension in either case.

i personally prefer typescript because i've never used closure

4. Also, any objections to documenting all of the external Pattern methods maybe with an @internal tag that disables autocomplete and maybe also hides them from the reference until we can improve the reference UI?

that would be awesome

[matthewkaney]

even though the function and the method are technically 2 things, they are conceptually the same from a language perspective. i think using the function directly is a very narrow use case, mostly practical for library users. i'm a bit worried that this might clutter the docs with info that is not useful for the majority of users.

That makes sense to me. There are some edge cases (I'm thinking of superimpose) where the two signatures are different in a meaningful way, but those could just be explained individually.