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

Don't publicly document Sprite constructor #67

Merged

Conversation

toolness
Copy link
Contributor

This is an attempt to fix #63.

It's a bit tricky, though: documenting the constructor as @private actually ends up marking the entire class as private, which prevents Sprite.html from being generated entirely! 😞

On top of that, it seemed impossible to add notes to the constructor advising users to use createSprite() instead: any documentation I tried adding either didn't show up, or it showed up in the class documentation, which is located waaaaay above the constructor. Meaning that users scrolling down to read the constructor docs likely wouldn't see the note about using createSprite.

So instead, I opted to simply remove the documentation for the constructor. It's still accessible from code, obviously, but it's undocumented now. Which IMO is probably a good thing, as it makes it that much less likely for users to accidentally use the constructor and then get confused when their sprite doesn't show up. However, it also means that there's no comments which help readers of the code understand what arguments the constructor takes. Suggestions welcome!

Oh, another thing: I'm using YUIDoc's crossLink helper here to directly link to the documentation for createSprite, but it's actually semi-broken at present due to kevinlacotaco/yuidoc-bootstrap-theme#24. Hopefully we can fix that soon, but at least for now it takes the user to the proper page, where they can manually find the createSprite method on their own.

@toolness toolness mentioned this pull request Mar 29, 2016
* @param {Number} width Width of the placeholder rectangle and of the
* collider until an image or new collider are set
* @param {Number} height Height of the placeholder rectangle and of the
* collider until an image or new collider are set
Copy link
Contributor

Choose a reason for hiding this comment

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

Could move this documentation of parameter types into a plain-old-JS-comment just inside the function, to preserve the documentation for devs without mucking up the generated documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That's a good idea... something like this maybe?

// For details on why these docs aren't in a YUIDoc comment block, see:
// 
// https://github.com/molleindustria/p5.play/pull/67
//
// @param {Number} x Initial x coordinate
// @param {Number} y Initial y coordinate
// @param {Number} width Width of the placeholder rectangle and of the
//                       collider until an image or new collider are set
// @param {Number} height Height of the placeholder rectangle and of the
//                        collider until an image or new collider are set

@toolness toolness merged commit a8bfb22 into quinton-ashley:master Mar 30, 2016
@quinton-ashley
Copy link
Owner

Undid this change since the move to ES6 classes requires it. Using the Sprite constructor is now equivalent to calling createSprite in v2.2.9

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.

Mark Sprite constructor as @private in docs?
3 participants