Use Yaml for parcelgen descriptions

[Pretz]

I am currently working on a heavy reworking of object descriptions to separate the API specific properties of an object from the application specific properties of an object. In the process I am moving from json to yaml for parcelable descriptions.

For instance, the Business.json included in the example project currently looks like this:

{
    "do_json": true,
    "package": "com.yelp.parcelgen",
    "json_map": {
        "uri": "url",
        "mobileUri": "mobile_url"
    },
    "props": {
        "Uri": [
            "uri",
            "mobileUri"
        ],
        "String": [
            "id",
            "name",
            "imageUrl",
            "phone",
            "displayPhone",
            "ratingImageUrl",
            "ratingImageUrlSmall",
            "snippetText",
            "snippetImageUrl"
        ],
        "int": [
            "reviewCount"
        ],
        "double": [
            "distance"
        ],
        "Location": [
            "location"
        ] 
    }
}

I'd like to change it to the following yaml description, which includes documentation for each property:

Location:
  location: Location data for this business
Float:
  distance: >
      Distance that business is from search location in meters, if a latitude/longitude
      is specified.
  rating: Rating for this business (value ranges from 1, 1.5, ... 4.5, 5)
Integer:
  review_count: Number of reviews for this business
String:
  display_phone: Phone number for this business formatted for display
  id: Yelp ID for this business
  name: Name of this business
  phone: Phone number for this business with international dialing code (e.g. +442079460000)
  snippet_text: Snippet text associated with this business
Url:
  url: URL for business page on Yelp
  image_url: URL of photo for this business
  mobile_url: URL for mobile business page on Yelp
  rating_img_url: URL to star rating image for this business (size = 84x17)
  rating_img_url_large: URL to large version of rating image for this business (size = 166x30)
  rating_img_url_small: URL to small version of rating image for this business (size = 50x10)
  snippet_image_url: URL of snippet image associated with this business

Note that the new yaml description uses the json properties as keys rather than the intended Java property names. Parcelgen will convert from underscore_separated to javaCamelCase when generating Java code.

Additionally, the implementation specific aspects of the parcelable description can be stored in a project level config file which will be used when generating Java code:

Target:
  language: java
  directory: src
  default_package: com.yelp.parcelgen
Config:
  Business:
    implement:
      - Serializable
    rename:
      url: uri
      mobile_url: mobileUri

[lxdvs]

I'm probably going to be leaving multiple comments here as I think of things to say.

1. This is awesome.
2. I would be a little hesitant to incude field-specific description information in the proposed project-level config file. This is because of my strong preference for collocation of descriptive information in supporting subsystems such as parcelgen. You could include default values straight in the base description file, as they are implementation-agnostic. Which brings me to my next point:
3. Can we just drop rename? Its stupid, and its implementation-specific. I actually want my POJO field getters to be consistently and trivially translatable to the json counterparts that I see in Charles or the server code, without having to even open the description file. One may Want to rename something for some reason, but one should just deal with it for the sake of ensured consistency.
4. Field documentation is going to get pulled in as javadoc right 😃

This is quite out of scope but:
5. Subobject shorthand. Here's the deal: I don't really think anybody really has a completely consistent model for API objects, and that needs addressing on multiple levels, but I have always thought that one of the awkward dissonances between the structure of parcelgen and real APIs (read: the yelp API) is deeply nested hierarchies. I want to be able to define one-off subobjects right in the middle of a description file (and in the resulting Java, these could be inner classes). I think you know what I'm talking about, but I can provide case examples of necessary.

[Pretz]

My overall goal is to make the parcelable description language agnostic. I'd like to make a tool where API builders could publish a set of parcelable descriptions, and developers could directly integrate those descriptions into their apps. That requires the parcelable description to have nothing to do with the app being used. Philosophically I agree with not using rename: it just adds a level of disconnect between the API and the app code. However, I'd like to keep Parcelgen compatible with its existing users and make it possible to use it with apps that previously built their model objects through other means, so I think rename will need to stay but should be discouraged.