Provided docstrings for client.py

[lenards]

Relates to #5

These docstrings are provided with Sphinx-style info field list formatting. The intended target of the documentation from the docstrings is "readthedocs" and it uses Sphinx.

The voice/tone of the documentation may not be satisfactory so only this file has been done to seek feedback.

[coveralls]

Coverage decreased (-1.52%) when pulling fe8841d on ajl/docstr-issue-5 into 5852368 on master.

[ewdurbin]

accepted values are http or https

[coveralls]

Coverage remained the same when pulling 62cbf70 on ajl/docstr-issue-5 into 5852368 on master.

[njm]

Alright, time to get anal! :) But only because Andy asked me to.

I like to document my classes as noun phrases -- objects are the nouns of programming after all -- and save the verbs for my methods and functions. This has the added benefit of cutting down on verbosity. Thus I'd suggest we simplify this to "Interface to the KISSmetrics tracking service" or something similar.

[ewdurbin]

i like where this is going. keep kicking ass dudez

[lenards]

@njm commit d2c89c5 has the changes that were suggested in comments.

Grammar is constant challenge for me (ask the co-authors on the few papers I attempted to write). Thank you for the feedback.

[coveralls]

Coverage remained the same when pulling d2c89c5 on ajl/docstr-issue-5 into 5852368 on master.

[ewdurbin]

Default host for tracking service endpoint

[ewdurbin]

so @lenards you can feel happy to fix our naming conventions within client.py on this PR per the following helpful ascii diagram:

  foo://username:password@example.com:8042/over/there/index.dtb?type=animal&name=narwhal#nose
  \_/   \_______________/ \_________/ \__/            \___/ \_/ \______________________/ \__/
   |           |               |       |                |    |            |                |
   |       userinfo         hostname  port              |    |          query          fragment
   |    \________________________________/\_____________|____|/ \__/        \__/
   |                    |                          |    |    |    |          |
   |                    |                          |    |    |    |          |
scheme              authority                    path   |    |    interpretable as keys
 name   \_______________________________________________|____|/       \____/     \_____/
   |                         |                          |    |          |           |
   |                 hierarchical part                  |    |    interpretable as values
   |                                                    |    |
   |            path               interpretable as filename |
   |   ___________|____________                              |
  / \ /                        \                             |
  urn:example:animal:ferret:nose               interpretable as extension

                path
         _________|________
 scheme /                  \
  name  userinfo  hostname       query
  _|__   ___|__   ____|____   _____|_____
 /    \ /      \ /         \ /           \
 mailto:username@example.com?subject=Topic

or i'll come through in one PR and get us lined up

[lenards]

I merged master into my PR to get the "remove QueryString class" and all the goodness from bcurtin

[coveralls]

Coverage remained the same when pulling d1d4909 on ajl/docstr-issue-5 into eeed6e6 on master.

[lenards]

I'll get this PR in-line with all the activity once the dust settles.

[lenards]

@ewdurbin & @njm - this is ready for review now, it is merged with master and has all feedback incorporated.

[lenards]

Now it's ready (spoke too soon)

[coveralls]

Coverage remained the same when pulling c5ab10c on ajl/docstr-issue-5 into 61ea233 on master.

[njm]

This is looking really good. My final nits are to do a quick s/$/./ on client_compat.py lines 48 and 134, and on query_string.py line 19 (since those are verb phrases). Other than that this gets a 👍 from me after Travis assures me it's all okay.

[coveralls]

Coverage remained the same when pulling 3cd41da on ajl/docstr-issue-5 into 61ea233 on master.

[coveralls]

Coverage remained the same when pulling a7f7d7b on ajl/docstr-issue-5 into 61ea233 on master.

[ewdurbin]

@lenards can you add an empty new line to all docstrings that need them?

[coveralls]

Coverage remained the same when pulling c50db42 on ajl/docstr-issue-5 into 61ea233 on master.

[coveralls]

Coverage remained the same when pulling c50db42 on ajl/docstr-issue-5 into 61ea233 on master.

[coveralls]

Coverage remained the same when pulling d8e9be0 on ajl/docstr-issue-5 into 61ea233 on master.

[coveralls]

Coverage remained the same when pulling d8e9be0 on ajl/docstr-issue-5 into 61ea233 on master.