Adding comments to remaining examples and HTML docs.

Adding comments to remaining examples and HTML docs.

[dhermes, 2012-12-07 21:48:51]

Adding hyperlinks to the docs and adding footnotes directing to the next sample.

[dhermes, 2012-12-08 00:10:09]

Adding some CSS and formatting to basic and basic_with_auth to better
distinguish between words and code.

[danielholevoet, 2012-12-08 00:14:04]

I made a few comments about how text didn't seem to appear with the correct code
blocks, but stopped after realizing this happened for many of the blocks. It
would be good to see if comment formatting can be improved to make the pairing
better, but I think you might have to make a pass through to adjust this by
hand.

Otherwise, I reviewed the text as it was, and tried to offer corrections for
clarity (or typos/punctuation/style).

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
File examples/custom_alias_properties/main.py (right):

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:31: # property "order". Though the
helper property "order" from EndpointsModel is
This sentence is confusing. Maybe: "The helper property order is not included in
the message schema, since we've defined our own "order". It would be included if
we had not defined our own schema."

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:52: # EndpointsModel.EntityKeySet use
to update the current entity using a
Missing comma after use.

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:97: # Since "id" is required, we
require that the request contain and "id" to be
and "id" => an "id"

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:99: # the "id" be sent in the request
by setting path='mymodel/{id}'. So to insert
Comma after "So" or remove "So".

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:121: # inserted entity will be that
passed in from the request.
that => the value

https://codereview.appspot.com/6903052/diff/2002/examples/simple_get/main.py
File examples/simple_get/main.py (right):

https://codereview.appspot.com/6903052/diff/2002/examples/simple_get/main.py#...
examples/simple_get/main.py:14: # In this model definition, we have included
_message_fields_schema to define
This comment doesn't line up with the definition of _message_fields_schema,
which IMO would be more helpful. This comment block (and the one immediately
following) should be paired with the code of this class.

https://codereview.appspot.com/6903052/diff/2002/examples/simple_get/main.py#...
examples/simple_get/main.py:44: # Here, since the schema includes an ID, it is
possible that the entity
This comment isn't paired with code. It should grouped with the comment
following.

[dhermes, 2012-12-08 00:56:12]

Removing lingering html in basic and more HTML layout updates to paging, filters
and custom messages.

[dhermes, 2012-12-08 00:57:22]

Adding last 2 examples to this review. They were left out by accident.

[dhermes, 2012-12-08 07:08:11]

Remaining 4 samples fully updated.

[dhermes, 2012-12-08 07:08:22]

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
File examples/custom_alias_properties/main.py (right):

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:31: # property "order". Though the
helper property "order" from EndpointsModel is
PTAL

On 2012/12/08 00:14:04, danielholevoet wrote:
> This sentence is confusing. Maybe: "The helper property order is not included
in
> the message schema, since we've defined our own "order". It would be included
if
> we had not defined our own schema."

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:52: # EndpointsModel.EntityKeySet use
to update the current entity using a
On 2012/12/08 00:14:04, danielholevoet wrote:
> Missing comma after use.

Done.

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:97: # Since "id" is required, we
require that the request contain and "id" to be
On 2012/12/08 00:14:04, danielholevoet wrote:
> and "id" => an "id"

Done.

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:99: # the "id" be sent in the request
by setting path='mymodel/{id}'. So to insert
On 2012/12/08 00:14:04, danielholevoet wrote:
> Comma after "So" or remove "So".

Done.

https://codereview.appspot.com/6903052/diff/2002/examples/custom_alias_proper...
examples/custom_alias_properties/main.py:121: # inserted entity will be that
passed in from the request.
On 2012/12/08 00:14:04, danielholevoet wrote:
> that => the value

Done.

https://codereview.appspot.com/6903052/diff/2002/examples/simple_get/main.py
File examples/simple_get/main.py (right):

https://codereview.appspot.com/6903052/diff/2002/examples/simple_get/main.py#...
examples/simple_get/main.py:14: # In this model definition, we have included
_message_fields_schema to define
On 2012/12/08 00:14:04, danielholevoet wrote:
> This comment doesn't line up with the definition of _message_fields_schema,
> which IMO would be more helpful. This comment block (and the one immediately
> following) should be paired with the code of this class.

Done.

https://codereview.appspot.com/6903052/diff/2002/examples/simple_get/main.py#...
examples/simple_get/main.py:44: # Here, since the schema includes an ID, it is
possible that the entity
On 2012/12/08 00:14:04, danielholevoet wrote:
> This comment isn't paired with code. It should grouped with the comment
> following.

Done.

[dhermes, 2012-12-08 07:34:43]

Adding link back to main page on bottom of all examples.

[dhermes, 2012-12-10 23:00:07]

Updating main page to point to endpoints sign up and refer to the needed
modules.

[danielholevoet, 2012-12-11 01:13:12]

Happy to comment further on the naming for protect_indexes. LGTM after the other
fixes.

https://codereview.appspot.com/6903052/diff/17001/docs/index.html
File docs/index.html (right):

https://codereview.appspot.com/6903052/diff/17001/docs/index.html#newcode44
docs/index.html:44: to specify exactly how data that is sent to and sent by APIs
written for Google
written for => written with

https://codereview.appspot.com/6903052/diff/17001/examples/basic/main.py
File examples/basic/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/basic/main.py#newc...
examples/basic/main.py:27: # Instead of the endpoints.method decorator, we can
use MyModel.method to
This is a run on sentence.

Also, should "endpoints.method decorator" be in two code blocks, or should
"decorator" be outside the block?

https://codereview.appspot.com/6903052/diff/17001/examples/basic_with_auth/ma...
File examples/basic_with_auth/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/basic_with_auth/ma...
examples/basic_with_auth/main.py:25: # message field -- a field whose value is
itself a message. To hold a user
mdash instead of --?

https://codereview.appspot.com/6903052/diff/17001/examples/basic_with_auth/ma...
examples/basic_with_auth/main.py:34: # we include it's client ID in audiences.
This is necessary for auth tokens
it's => its

https://codereview.appspot.com/6903052/diff/17001/examples/custom_alias_prope...
File examples/custom_alias_properties/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/custom_alias_prope...
examples/custom_alias_properties/main.py:5: # how these properties -- called
alias properties -- are used. For more
Same comment about -- versus —.

https://codereview.appspot.com/6903052/diff/17001/examples/keys_with_ancestor...
File examples/keys_with_ancestors/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/keys_with_ancestor...
examples/keys_with_ancestors/main.py:8: # which have an ancestor -- for example
ndb.Key(MyParent, ..., MyModel, ...) --
Same comment about -- versus —.

https://codereview.appspot.com/6903052/diff/17001/examples/protect_indexes/ma...
File examples/protect_indexes/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/protect_indexes/ma...
examples/protect_indexes/main.py:6: # indexes created in index.yaml.
I think maybe this sample should have a different name. "Limiting queries"
maybe?

https://codereview.appspot.com/6903052/diff/17001/examples/simple_get/main.py
File examples/simple_get/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/simple_get/main.py...
examples/simple_get/main.py:30: # properties used for queries -- limit, order,
pageToken -- which are
Same comment about -- versus —.

https://codereview.appspot.com/6903052/diff/17001/examples/simple_get/main.py...
examples/simple_get/main.py:55: # This method is not defined in any of the
previous examples; it allows an
; => :

[dhermes, 2012-12-11 02:50:29]

Updating after final round of review. Still need to decide on a rename for
protect_indexes.

[dhermes, 2012-12-11 02:50:50]

https://codereview.appspot.com/6903052/diff/17001/docs/index.html
File docs/index.html (right):

https://codereview.appspot.com/6903052/diff/17001/docs/index.html#newcode44
docs/index.html:44: to specify exactly how data that is sent to and sent by APIs
written for Google
On 2012/12/11 01:13:13, danielholevoet wrote:
> written for => written with

Done.

https://codereview.appspot.com/6903052/diff/17001/examples/basic/main.py
File examples/basic/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/basic/main.py#newc...
examples/basic/main.py:27: # Instead of the endpoints.method decorator, we can
use MyModel.method to
Split into two sentences.

Good find, decorator does not belong in the code block.

On 2012/12/11 01:13:13, danielholevoet wrote:
> This is a run on sentence.
> 
> Also, should "endpoints.method decorator" be in two code blocks, or should
> "decorator" be outside the block?

https://codereview.appspot.com/6903052/diff/17001/examples/basic_with_auth/ma...
File examples/basic_with_auth/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/basic_with_auth/ma...
examples/basic_with_auth/main.py:25: # message field -- a field whose value is
itself a message. To hold a user
On 2012/12/11 01:13:13, danielholevoet wrote:
> mdash instead of --?

Done.

https://codereview.appspot.com/6903052/diff/17001/examples/basic_with_auth/ma...
examples/basic_with_auth/main.py:34: # we include it's client ID in audiences.
This is necessary for auth tokens
On 2012/12/11 01:13:13, danielholevoet wrote:
> it's => its

Done.

https://codereview.appspot.com/6903052/diff/17001/examples/custom_alias_prope...
File examples/custom_alias_properties/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/custom_alias_prope...
examples/custom_alias_properties/main.py:5: # how these properties -- called
alias properties -- are used. For more
On 2012/12/11 01:13:13, danielholevoet wrote:
> Same comment about -- versus —.

Done.

https://codereview.appspot.com/6903052/diff/17001/examples/keys_with_ancestor...
File examples/keys_with_ancestors/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/keys_with_ancestor...
examples/keys_with_ancestors/main.py:8: # which have an ancestor -- for example
ndb.Key(MyParent, ..., MyModel, ...) --
On 2012/12/11 01:13:13, danielholevoet wrote:
> Same comment about -- versus —.

Done.

https://codereview.appspot.com/6903052/diff/17001/examples/protect_indexes/ma...
File examples/protect_indexes/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/protect_indexes/ma...
examples/protect_indexes/main.py:6: # indexes created in index.yaml.
Let's discuss in person. I am not married to the name "protect_indexes", but
think that index should be in the name.

On 2012/12/11 01:13:13, danielholevoet wrote:
> I think maybe this sample should have a different name. "Limiting queries"
> maybe?

https://codereview.appspot.com/6903052/diff/17001/examples/simple_get/main.py
File examples/simple_get/main.py (right):

https://codereview.appspot.com/6903052/diff/17001/examples/simple_get/main.py...
examples/simple_get/main.py:30: # properties used for queries -- limit, order,
pageToken -- which are
On 2012/12/11 01:13:13, danielholevoet wrote:
> Same comment about -- versus —.

Done.

https://codereview.appspot.com/6903052/diff/17001/examples/simple_get/main.py...
examples/simple_get/main.py:55: # This method is not defined in any of the
previous examples; it allows an
On 2012/12/11 01:13:13, danielholevoet wrote:
> ; => :

Done.

[dhermes, 2012-12-11 18:36:23]

Final rename to matching_queries_to_indexes.

[dhermes, 2012-12-11 18:43:27]

Changing Google APIs explorer text to hyper refs.

[dhermes, 2012-12-11 18:46:09]

Added in
http://code.google.com/p/endpoints-proto-datastore/source/detail?r=6776b7343a...

[dhermes, 2013-01-18 06:59:32]

The commit this was added in has since moved to

http://code.google.com/p/endpoints-proto-datastore/source/detail?r=071564fae5...

since the repository migrated from mercurial to git.