Adding usage doc for Natural Language API.

[dhermes]

/cc @omaray are you in the org yet (I can't assign you to this PR)

[tseaver]

A couple of more general questions:

• Shouldn't this PR (and subsequent implementation PRs) target a natural-language-feature branch?
• Should we be packaging up the JSON results for the three APIs into objects?

[dhermes]

@tseaver Can you weigh in here on which response values you think we should wrap?

[elibixby]

@jerjou Can you take a look to make sure we have someone who has used the API a bit to comment on usability.

[tseaver]

Can you weigh in here on which response values you think we should wrap?

For analyze_entities, we could return instances of a (putative) Entity class:

forentityindocument.analyze_entities():
build_entity_link(entity.name, entity.type, entity.url)

For analyze_sentiment, we could return a (putative) Sentiment instance:

defby_sentiment(document):
"""Sort key: rank from most negative to most positive."""sentiment=document.analyze_sentiment()
returnsentiment.polarity*sentiment.magnituderanked=sorted(documents, key=by_sentiment)

For annotate_text, (assuming we have flags to disable unwanted features):

only_syntax=document.annotate_text(
include_entities=False, include_sentiment=False)
assertonly_syntax.entitiesisNoneassertonly_syntax.sentimentisNonetree=ParseTree() # imagined class w/ 'add_token' method.forindex, tokeninenumerate(only_syntax.tokens):
edge=token.dependency_edgetree.add_token(
index, token.lemma, token.part_of_speech, edge.head_index, edge.label)

[tseaver]

LGTM.

[dhermes]

@jgeewax In the interest of keeping this PR from reaching 15 days of age, I'll merge with @tseaver's LGTM and we can address after the fact as the API develops (it's a small surface area so it won't be overwhelming).