Documentation

Design.md

@@ -1,27 +1,49 @@
-Object:
+Typology of URLs
+================
 
-  - GET-able or not: lazy on attribute reading
-  - PATCH-able or not: object.edit( ... )
-  - DELETE-able or not: object.delete()
-  - has attributes
-    - scalars (in the GET for the object)
-    - lists (in a specific GET)
+Object URLs
+-----------
 
-Scalar:
+They
 
-  - fondamental type or objet
+ - return a single object on GET
+ - may be PATCH-able (to modify the object)
+ - may be DELETE-able (to... delete the object)
 
-List:
+List URLs
+---------
 
-  - contains fondamental type or objet
-  - GET-able or not
-  - elements GET-able or not
-    - to ask if an element is in the list
-  - elements PUT-able or not
-    - add an existing element to the list: parent.add_to_elements( element )
-  - POST-able or not
-    - create a new element and add it to the list: parent.create_element( ... )
-  - elements DELETE-able or not
-    - delete an element from a list can have two meanings:
-      - the element's life is finished: element.delete()
-      - the element is just removed from the list, but continues to live somewhere else: parent.remove_from_elements( element )
+They
+
+ - return a list of objects on GET (some of them are not GET-able)
+ - may be POST-able (to create a new object)
+ - may have specific URLs for their elements, that
+   - may be PUT-able (to add an existing object to this list)
+   - may be GET-able (to ask if an object is in the list)
+   - may be DELETE-able (to remove an object from the list)
+
+Lazyness
+========
+
+An URL returning a list of objects returns most of the information
+about its elements, but not all. So, we have a lazy completion for
+objects returned by the API: we do a GET on their object URL when
+the user asks an attribute we have not got from the list of objects.
+
+We don't use lazy completion for objects requested by name by user,
+to detect name errors as soon as possible.
+
+Attributes vs. methods
+======================
+
+We have methods for API calls, and attributes for in-memory reads
+(except for lazy attributes that may trigger a call to an URL).
+Methods are named with a verb prefix to avoid name clashes with attributes.
+(`followers` is an attribute of User giving the number of followers,
+and `get_followers` is a method returning the list of followers)
+
+Explicit `edit` methods
+=======================
+
+To modify objects, we have a single `edit` method (not several
+writable attributes) to be explicit about API calls.

Reference.md

@@ -7,8 +7,8 @@ Contents
 Classes
 =======
 
-One doesn't normaly create instances of any class but Github.
-One obtains instances through calls to `get_` and `create_` methods.
+You don't normaly create instances of any class but Github.
+You obtain instances through calls to `get_` and `create_` methods.
 
 In this documentation:
 
@@ -28,7 +28,8 @@ Class `Github`
 Class `AuthenticatedUser`
 -------------------------
 
- - `edit( ... )`
+ - Attributes: see [API](http://developer.github.com/v3/...#...) (TODO)
+ - `edit( ... )`: see [API](http://developer.github.com/v3/...#...) (TODO) for parameters
 
 ### Repositories
 
@@ -59,6 +60,8 @@ Class `AuthenticatedUser`
 Class `NamedUser`
 -----------------
 
+ - Attributes: see [API](http://developer.github.com/v3/...#...) (TODO)
+
 ### Repositories
 
  - `get_repos()`: list of `Repository` (TODO: add type parameter)
@@ -80,7 +83,8 @@ Class `NamedUser`
 Class `Organization`
 --------------------
 
- - `edit( ... )`
+ - Attributes: see [API](http://developer.github.com/v3/...#...) (TODO)
+ - `edit( ... )`: see [API](http://developer.github.com/v3/...#...) (TODO) for parameters
 
 ### Repositories
 
@@ -102,7 +106,8 @@ Class `Organization`
 Class `Repository`
 ------------------
 
- - `edit( ... )`
+ - Attributes: see [API](http://developer.github.com/v3/...#...) (TODO)
+ - `edit( ... )`: see [API](http://developer.github.com/v3/...#...) (TODO) for parameters
 
 ### Collaborators
 

RoadMap.md

@@ -1,17 +1,5 @@
 Documentation
 =============
- - tutorial
- - classes for Github objects
-   - how to get instances of them
-   - properties
-   - methods (and arguments)
- - api and how it is wrapped
- - rationale:
-   - lazyness for objects returned by API, not for objects requested by user
-   - naming: get_xxx() to avoid clashes with attribute xxx (User.followers for example), and to explicit api calls. One get_ <=> one api call. No get_ <=> no api call, most often, and one from time to time to complete an object.
-   - lazy completion, but no caching
-   - explicit edit instead of writeable attributes
-   - data model (cf Design.md)
 
 Functional improvements
 =======================