Reference document improvements.

Summary: Expanded comments, language cleanup.

Test Plan:
Run build_documentation.sh, then moved files to proper place so they showed up in Xcode organizer and verified improvements.

Revert Plan:
OK

Reviewers: jacl

Reviewed By: jacl

CC: clang, mmarucheck, ayden, platform-diffs@lists

Differential Revision: https://phabricator.fb.com/D497094

src/FBGraphLocation.h

@@ -21,53 +21,56 @@
  @protocol
  
  @abstract
- A graph accessor protocol used to access location information
+ The `FBGraphLocation` protocol enables typed access to the `location` property
+ of a Facebook place object.
+
  
  @discussion
- Represents commonly used properties of a Facebook place object, may be used to access an NSDictionary object for which
- the graphObjectWrappingDictionary method has been called; graph accessors enable typed access to Facebook graph objects
+ The `FBGraphLocation` protocol represents the most commonly used properties of a 
+ location object. It may be used to access an `NSDictionary` object that has
+ been wrapped with an <FBGraphObject> facade.
  */
 @protocol FBGraphLocation<FBGraphObject>
 
 /*!
  @property
- @abstract Typed access to location's street
+ @abstract Typed access to a location's street.
  */
 @property (retain, nonatomic) NSString *street;
 
 /*!
  @property
- @abstract Typed access to location's city
+ @abstract Typed access to a location's city.
  */
 @property (retain, nonatomic) NSString *city;
 
 /*!
  @property
- @abstract Typed access to location's state
+ @abstract Typed access to a location's state.
  */
 @property (retain, nonatomic) NSString *state;
 
 /*!
  @property
- @abstract Typed access to location's country
+ @abstract Typed access to a location's country.
  */
 @property (retain, nonatomic) NSString *country;
 
 /*!
  @property
- @abstract Typed access to location's zip
+ @abstract Typed access to a location's zip code.
  */
 @property (retain, nonatomic) NSString *zip;
 
 /*!
  @property
- @abstract Typed access to location's latitude
+ @abstract Typed access to a location's latitude.
  */
 @property (retain, nonatomic) NSNumber *latitude; 
 
 /*!
  @property
- @abstract Typed access to location's longitude
+ @abstract Typed access to a location's longitude.
  */
 @property (retain, nonatomic) NSNumber *longitude;
 

src/FBGraphPlace.h

@@ -22,36 +22,38 @@
  @protocol 
  
  @abstract
- A graph accessor protocol used to access information about places
+ The `FBGraphPlace` protocol enables typed access to a place object
+ as represented in the Graph API.
+
  
  @discussion
- Represents commonly used properties of a Facebook place object, may be used to access an 
- NSDictionary object for which the treatAsGraphObject method has been called; graph accessors 
- enable typed access to Facebook graph objects
+ The `FBGraphPlace` protocol represents the most commonly used properties of a 
+ Facebook place object. It may be used to access an `NSDictionary` object that has
+ been wrapped with an <FBGraphObject> facade.
  */
 @protocol FBGraphPlace<FBGraphObject>
 
 /*!
  @property
- @abstract Typed access to place's id
+ @abstract Typed access to the place ID.
  */
 @property (retain, nonatomic) NSString *id;
 
 /*!
  @property
- @abstract Typed access to place's name
+ @abstract Typed access to the place name.
  */
 @property (retain, nonatomic) NSString *name;
 
 /*!
  @property
- @abstract Typed access to place's id
+ @abstract Typed access to the place category.
  */
 @property (retain, nonatomic) NSString *category;
 
 /*!
  @property
- @abstract Typed access to place's id
+ @abstract Typed access to the place location.
  */
 @property (retain, nonatomic) id<FBGraphLocation> location;
 

src/FBGraphUser.h

@@ -22,66 +22,68 @@
  @protocol 
  
  @abstract
- A graph accessor protocol used to access facebook user information
+ The `FBGraphUser` protocol enables typed access to a user object
+ as represented in the Graph API.
+
  
  @discussion
- Represents commonly used properties of a Facebook User object, may be used to access an
- NSDictionary object for which the treatAsGraphObject method has been called; graph accessors 
- enable typed access to Facebook graph objects
+ The `FBGraphUser` protocol represents the most commonly used properties of a 
+ Facebook user object. It may be used to access an `NSDictionary` object that has
+ been wrapped with an <FBGraphObject> facade.
  */
 @protocol FBGraphUser<FBGraphObject>
 
 /*!
  @property
- @abstract Typed access to user's id
+ @abstract Typed access to the user's ID.
  */
 @property (retain, nonatomic) NSString *id;
 
 /*!
  @property
- @abstract Typed access to user's name
+ @abstract Typed access to the user's name.
  */
 @property (retain, nonatomic) NSString *name;
 
 /*!
  @property
- @abstract Typed access to user's first name
+ @abstract Typed access to the user's first name.
  */
 @property (retain, nonatomic) NSString *first_name;
 
 /*!
  @property
- @abstract Typed access to user's middle name
+ @abstract Typed access to the user's middle name.
  */
 @property (retain, nonatomic) NSString *middle_name;
 
 /*!
  @property
- @abstract Typed access to user's last name
+ @abstract Typed access to the user's last name.
  */
 @property (retain, nonatomic) NSString *last_name;
 
 /*!
  @property 
- @abstract Typed access to user's link
+ @abstract Typed access to the user's profile URL.
  */
 @property (retain, nonatomic) NSString *link;
 
 /*!
  @property 
- @abstract Typed access to user's username
+ @abstract Typed access to the user's username.
  */
 @property (retain, nonatomic) NSString *username;
 
 /*!
  @property 
- @abstract Typed access to user's birthday
+ @abstract Typed access to the user's birthday.
  */
 @property (retain, nonatomic) NSString *birthday;
 
 /*!
  @property 
- @abstract Typed access to user's location
+ @abstract Typed access to the user's current city.
  */
 @property (retain, nonatomic) id<FBGraphLocation> location;
 

src/FBProfilePictureView.h

@@ -25,50 +25,52 @@
  @discussion
  */
 typedef enum {
-    /*! Original (default) - the original profile picture, as uploaded */
+    /*! Original (default) - the original profile picture, as uploaded. */
     FBProfilePictureCroppingOriginal    = 0,
 
-    /*! Square - the square version that the Facebook user defined */
+    /*! Square - the square version that the Facebook user defined. */
     FBProfilePictureCroppingSquare      = 1
 
 } FBProfilePictureCropping;
 
 /*!
  @class
  @abstract
- View used to display a profile picture.  Default behavior of this control centers the profile picture
- in the control and shrinks it, if necessary, to the controls bounds, preserving aspect ratio. The smallest
- possible image is downloaded to ensure that scaling up never happens.  Resizing the control may result in 
+ An instance of `FBProfilePictureView` is used to display a profile picture.  
+ 
+ The default behavior of this control is to center the profile picture
+ in the view and shrinks it, if necessary, to the view's bounds, preserving the aspect ratio. The smallest
+ possible image is downloaded to ensure that scaling up never happens.  Resizing the view may result in 
  a different size of the image being loaded.  Canonical image sizes are documented in the "Pictures" section
  of https://developers.facebook.com/docs/reference/api. 
  */
 @interface FBProfilePictureView : UIView
 
 /*!
  @abstract
- Specifies the fbid for the user, place or object for which a picture should be fetched and displayed
+ The Facebook ID of the user, place or object for which a picture should be fetched and displayed.
  */
 @property (copy, nonatomic) NSString* userID;
 
 /*!
  @abstract
- Specifies which cropping of the profile picture to use.
+ The cropping to use for the profile picture.
  */
 @property (nonatomic) FBProfilePictureCropping pictureCropping;
 
 /*!
  @abstract
- Initializes and returns a ProfilePictureView
+ Initializes and returns a profile view object.
  */
 - (id)init;
 
 
 /*!
  @abstract
- Initializes and returns a ProfilePictureView
+ Initializes and returns a profile view object for the given Facebook ID and cropping.
  
- @param userID          Specifies the fbid for the object for which a picture should be fetched and displayed
- @param pictureCropping Specifies the cropping for the picture displayed.
+ @param userID          The Facebook ID of the user, place or object for which a picture should be fetched and displayed.
+ @param pictureCropping The cropping to use for the profile picture.
  */
 - (id)initWithUserID:(NSString*)userID 
   andPictureCropping:(FBProfilePictureCropping)pictureCropping;