Add yuidoc blocks to pager-control.js, see #223

[pixelhandler]

What's in this PR?

• Added yuidoc blocks in app/components/pager-control.js file

Progress on: #223

[rileytaylor]

Good start, but this is pretty bare bones. Check out this one for an example: https://github.com/code-corps/code-corps-ember/blob/develop/app/components/project-card-skills.js and check out https://github.com/code-corps/code-corps-ember/blob/develop/.github/CONTRIBUTING.md#what-kind-of-documentation-are-you-writing for documentation how to.

[joshsmith]

@rileytaylor @pixelhandler it's a good question as to what extent we're overdocumenting in other cases and if this is the right level of documentation here. Are some of these functions self-documenting enough just by naming convention? I'm not totally positive, but am certainly open to some competing ideas here to see what direction we should take.

[rileytaylor]

@joshsmith @pixelhandler agreed. Some of the simple boolean values could go without description, but some could definitely use @default tags. Also the beginning header describing the entire component.

[pixelhandler]

@joshsmith

Are some of these functions self-documenting enough just by naming convention?

If you plan to use generated docs, only methods with doc blocks will show up. For example here are the generated docs I use for an addon project, http://ember-jsonapi-resources.com/docs/

[pixelhandler]

@rileytaylor I'll add the defaults and the component doc block as well, thanks

[joshsmith]

@pixelhandler I wasn't clear: I meant that you didn't need much more than @property canShowPages, for example, given the self-documenting nature.

[pixelhandler]

@joshsmith cool thanks for the clarity, I do like seeing @type w/ @property

[joshsmith]

I was unclear again! I just meant that you didn't need extra English-language description about what it means.

[pixelhandler]

@joshsmith with generated docs the English language description can be handy even when the property name is super targeted, there is usually some clarity that can be added. Also the generated docs too read nice with human descriptions vs variable names only, here is another example page of props, http://ember-jsonapi-resources.com/docs/classes/ApplicationAdapter.html

[joshsmith]

Okay, then I would definitely consider adding those descriptions here, then.

[pixelhandler]

@rileytaylor @joshsmith I updated this PR after rebasing on develop, Added doc block for the component as well as human friendly descriptions for the properties.

[WenInCode]

I've reviewed the previous feedback, and checked out the latest changes. This LGTM thanks @pixelhandler

Feel free to squash & merge

[joshsmith]

👍 please do rebase and squash when you can @pixelhandler!

[pixelhandler]

@joshsmith I rebased and squashed; so CI should run again :)

[pixelhandler]

@rileytaylor do you need to 👍 for the requested changes ?

[rileytaylor]

yes, looks like I do! Looks good now.

[joshsmith]

🙌