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 improvements and cleanup #1891

Merged
merged 6 commits into from
Jul 7, 2014
Merged

Documentation improvements and cleanup #1891

merged 6 commits into from
Jul 7, 2014

Conversation

shunter
Copy link
Contributor

@shunter shunter commented Jul 7, 2014

  • Document functions with callback syntax to specify parameters and return values. Fixes Standardize callback/function parameter documentation #1085.
    • Some are still listed as Function because they don't have a strict interface. For example, the signature of an Event listener varies from instance to instance.
  • Switch modules which create a "namespace" which holds static values, functions, etc. - but does not provide a constructor - to use @namespace syntax instead of @exports.
    • This allows changing the template to include function signatures for @exports. Going forward, @exports are assumed to be free functions.

* A function used to compare two items while sorting a queue.
* @callback Queue~Comparator
*
* @param {Object} a An item in the array.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be better to use left and right here instead of a and b? That's the convention we seem to use elsewhere.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

left and right make somewhat more sense for something like equals, which in better languages would be defined as infix operators, e.g. left == right. Comparison functions seem to generally be different. MDN for JavaScript uses a, b. Java uses o1, o2. .NET uses x, y.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fine by me.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this ready then?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah.

@mramato
Copy link
Contributor

mramato commented Jul 7, 2014

Other than the couple of minor comments, this looks good to me.

mramato added a commit that referenced this pull request Jul 7, 2014
@mramato mramato merged commit 8486227 into master Jul 7, 2014
@mramato mramato deleted the documentFunctions branch July 7, 2014 19:19
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.

Standardize callback/function parameter documentation
2 participants