improve documentation to explain parameter values/defaults #22

Open
astanley opened this Issue Mar 20, 2012 · 2 comments

Comments

Projects
None yet
2 participants
@astanley

I had some trouble understanding what values & format were accepted for each parameter of the animation methods. I think there is an opportunity to improve the documentation (or code comments / samples) to make this easier for developers who aren't already familiar with the framework

For example: I see the last parameter of the slide() method is playstate, and one code snippet shows that an eligible value is "running". What do either of these mean (what is a playstate)? What are other values besides 'running' that can be used instead? How would a developer know what values to fill in?

@psiborg

This comment has been minimized.

Show comment Hide comment
@psiborg

psiborg Mar 20, 2012

Contributor

The possible values for playstate are "running" and "paused", which are standard CSS values for that animation property. I haven't really had a need for "pause" yet, but I left it in case developers don't want an animation to start right away. This allows them to control when it starts programmatically. But your suggestions about better documentation are spot on. Thanks Adam!

Contributor

psiborg commented Mar 20, 2012

The possible values for playstate are "running" and "paused", which are standard CSS values for that animation property. I haven't really had a need for "pause" yet, but I left it in case developers don't want an animation to start right away. This allows them to control when it starts programmatically. But your suggestions about better documentation are spot on. Thanks Adam!

@astanley

This comment has been minimized.

Show comment Hide comment
@astanley

astanley Mar 21, 2012

Thanks for explaining. Maybe if there was a master table somewhere that listed all parameters for each method, followed by all eligible values / formats, it might help new developers?

I completely understand that some keywords are standard CSS values, but I would think since AliceJS abstracts the raw CSS from the developers, that developers should be given some assistance in learning what these values are. Otherwise how would they know?

e.g. for comments associated with the methods, should the [type] and [description] keywords be replaced with something more meaningful?

/**

  • [zoom description]
  • @param {[type]} elems [description]
  • @param {[type]} scale [description]
  • @param {[type]} shadow [description]
  • @param {[type]} move [description]
  • @param {[type]} duration [description]
  • @param {[type]} timing [description]
  • @param {[type]} delay [description]
  • @param {[type]} iteration [description]
  • @param {[type]} direction [description]
  • @param {[type]} playstate [description]
  • @return {[type]}
    */

Thanks for explaining. Maybe if there was a master table somewhere that listed all parameters for each method, followed by all eligible values / formats, it might help new developers?

I completely understand that some keywords are standard CSS values, but I would think since AliceJS abstracts the raw CSS from the developers, that developers should be given some assistance in learning what these values are. Otherwise how would they know?

e.g. for comments associated with the methods, should the [type] and [description] keywords be replaced with something more meaningful?

/**

  • [zoom description]
  • @param {[type]} elems [description]
  • @param {[type]} scale [description]
  • @param {[type]} shadow [description]
  • @param {[type]} move [description]
  • @param {[type]} duration [description]
  • @param {[type]} timing [description]
  • @param {[type]} delay [description]
  • @param {[type]} iteration [description]
  • @param {[type]} direction [description]
  • @param {[type]} playstate [description]
  • @return {[type]}
    */
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment