Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Update #1270

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

matthewkaney
Copy link
Contributor

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant