Documentation edits

Edit the documentation for minor grammar, idiomatic usage, and sentence construction issues.  Overall the documentation is great;  this is just cleaning up some places that sound a little odd.

There are some notes left in the documentation delimited by [bwb: ...] where I made a larger-than-usual change or I thought needed attention from someone more familiar with the codebase than I am.



On Nov 4, 2014, at 2:38 AM, Christian Kaps <notifications@github.com> wrote:

> In docs/how-it-works/authenticator.rst:
> 
> >  services can validate a retrieved authenticator, based on its ID, against a backing store.
> >  Silhouette automatically tries to retrieve an authenticator on every request to a
> >  :ref:`Silhouette action <silhouette_actions>`.
> >  
> >  Init an authenticator
> >  ^^^^^^^^^^^^^^^^^^^^^
> > +[bwb: I think "init" is a confusing name for this method. Perhaps "embed"?].
> I think in an old release I chose embed as name for the method. But the method doesn't embed the authenticator only. It saves also the authenticator in the backing store. So I thought init would be a better name because it initializes the authenticator server and client side.
> 
It looks to me like init should actually be part of authenticator creation. In the seed code, at least, it always happens immediately after creation and never separate from creation. 

It may make sense to have it as a separate method so that it can be overridden, but I don’t like the need to call both create and init together and in the correct order.  There’s also the confusion factor of what exactly is the difference between creating an authenticator and initializing an authenticator.  

I’m going to document the way I think it should happen but wait to change actual code until I hear back.

The downside of doing this is that it breaks existing code.  But we’re doing lots of that with the 2.0 update.

Byron

---------------------------------------------
Byron Weber Becker
School of Computer Science
University of Waterloo, Waterloo, Ontario  N2L 3G1
Email: bwbecker@uwaterloo.ca
Phone:  519-888-4567 x38331
Fax:  519-888-4380 (include my email on cover page)

Advising FAQ:  www.cs.uwaterloo.ca/current/faq