Documentation: SkCanvas API

Documentation: SkCanvas API
NOTRY=true
DOCS_PREVIEW= https://skia.org/?cl=1127383010
DOCS_PREVIEW= https://skia.org/user/api?cl=1127383010
DOCS_PREVIEW= https://skia.org/user/api/skcanvas?cl=1127383010
DOCS_PREVIEW= https://skia.org/user/api/skpaint?cl=1127383010
DOCS_PREVIEW= https://skia.org/user/api/skrect?cl=1127383010
DOCS_PREVIEW= https://skia.org/user/api/skregion?cl=1127383010
DOCS_PREVIEW= https://skia.org/user/api/skmatrix?cl=1127383010
DOCS_PREVIEW= https://skia.org/user/api/canvas?cl=1127383010

Committed: https://skia.googlesource.com/skia/+/ee2a8eede9ba9efd34cd132c5abc175f9c434b7a

[hal.canary, 2015-05-13 14:03:19]

halcanary@google.com changed reviewers:
+ scroggo@google.com

[hal.canary, 2015-05-13 14:03:19]

PTAL

[scroggo, 2015-05-13 14:51:15]

lgtm

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md
File site/user/api/canvas.md (right):

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:55: void(*drawable)(SkCanvas*),
nit: Since this is a function pointer, I'm not sure "drawable" is the best name.
(It also makes me think of SkDrawable, which this is not.)

Why not just "draw"? (I think I like "draw" here because it is a verb.)

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:149: DEF_TEST(FourBackends, r) {
A danger in telling the user to copy and paste code is that it may not work
later when we change the API.

Long term I think we should be testing whatever our documentation recommends,
but I am not aware that we have that yet, and it shouldn't necessarily block
this CL.

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/index.md
File site/user/api/index.md (right):

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/index.md#...
site/user/api/index.md:1: API Overview & Doxygen Docs
Did this move? Why?

[reed1, 2015-05-13 15:44:15]

reed@google.com changed reviewers:
+ reed@google.com

[reed1, 2015-05-13 15:44:16]

This has a lot of tricky factory/ptr machinery in place. I wonder if that is
needed to convey how to use skia for a beginner.

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md
File site/user/api/canvas.md (right):

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:14: float scale = 256.0f;
Lets use SkScalar in the dox

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:16: canvas->clear(SK_ColorWHITE);
logically, we should probably issue the clear first (with a comment), since it
is unaffected by the translate

[hal.canary, 2015-05-13 15:45:33]

On 2015/05/13 15:44:16, reed1 wrote:
> This has a lot of tricky factory/ptr machinery in place. I wonder if that is
> needed to convey how to use skia for a beginner.

How can I make it simpler?

[reed1, 2015-05-13 16:07:13]

One thought is to talk about SkCanvas a lot, and then piece-meal you can talk
about about adding the complexity of 
- which surface type
- documents -vs- surfaces
- pictures -vs- surfaces
but hitting them w/ all 4, with little/no context might be overwhelming

[hal.canary, 2015-05-13 17:58:24]

I amended the CL by pulling in most of what was in the old Wiki.

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md
File site/user/api/canvas.md (right):

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:14: float scale = 256.0f;
On 2015/05/13 15:44:16, reed1 wrote:
> Lets use SkScalar in the dox

Done.

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:16: canvas->clear(SK_ColorWHITE);
On 2015/05/13 15:44:16, reed1 wrote:
> logically, we should probably issue the clear first (with a comment), since it
> is unaffected by the translate

Done.

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:55: void(*drawable)(SkCanvas*),
On 2015/05/13 14:51:15, scroggo wrote:
> nit: Since this is a function pointer, I'm not sure "drawable" is the best
name.
> (It also makes me think of SkDrawable, which this is not.)
> 
> Why not just "draw"? (I think I like "draw" here because it is a verb.)

Done.

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/canvas.md...
site/user/api/canvas.md:149: DEF_TEST(FourBackends, r) {
On 2015/05/13 14:51:15, scroggo wrote:
> A danger in telling the user to copy and paste code is that it may not work
> later when we change the API.
> 
> Long term I think we should be testing whatever our documentation recommends,
> but I am not aware that we have that yet, and it shouldn't necessarily block
> this CL.

Acknowledged.

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/index.md
File site/user/api/index.md (right):

https://codereview.chromium.org/1127383010/diff/80001/site/user/api/index.md#...
site/user/api/index.md:1: API Overview & Doxygen Docs
On 2015/05/13 14:51:15, scroggo wrote:
> Did this move? Why?

I wanted to make it the top-level doc for API documentation.

[hal.canary, 2015-05-19 17:20:26]

The CQ bit was checked by halcanary@google.com

[hal.canary, 2015-05-19 17:20:27]

The patchset sent to the CQ was uploaded after l-g-t-m from scroggo@google.com
Link to the patchset: https://codereview.chromium.org/1127383010/#ps510001
(title: "2015-05-19 (Tuesday) 13:19:57 EDT")

[commit-bot: I haz the power, 2015-05-19 17:21:03]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/1127383010/510001

[commit-bot: I haz the power, 2015-05-19 17:21:37]

Committed patchset #28 (id:510001) as
https://skia.googlesource.com/skia/+/ee2a8eede9ba9efd34cd132c5abc175f9c434b7a