README.md in rapi_doc-0.3.1 vs README.md in rapi_doc-0.4.0

@@ -11,23 +11,82 @@
 `gem install rapi_doc`
 
 Usage
 =====
 
-Run `rake rapi_doc:setup` to generate config and layout files.
+Run `rake rapi_doc:setup` to generate default Haml template files along with default styles.
+These files are in `<application folder>/config/rapi_doc` folder. 
 
-Modify config file by adding your controllers, e.g.:
-
-    books:
-      location: "/books"
-      controller_name: "books_controller.rb"
-
 Then invoke the generation by calling:
 
 `rake rapi_doc:generate`
 
-Documentation Example
+It will analyze `rake routes` output and find the controller files in app/controllers directory that may have the annotation.
+It will confirm from the user whether he/she wants the plugin to look for annotations in each of these files.
+For files confirmed by the user, it will parse the annotations and generate the HTML output using the template files and styles
+in the `config/rapi_doc` folder.
+
+`rake rapi_doc:clean`
+will remove the documentation thus generated.
+
+`rake rapi_doc:distclean`
+will remove the documentation and also the Haml template files and styles created by the `rake rapi_doc:setup`
+
+
+Markup Reference
+================
+
+Controller methods and controllers themselves are documented by annotating them with "method markers" and
+"resource markers" enclosed in "apidoc" comments, similar to that in RDoc.
+
+  # =begin apidoc
+  ... method markers
+  # =end
+
+A] Method markers
+-----------------
+
+Method markers are specified like this:
+
+    # <<method-marker-name>:: <method-marker-value>
+
+All method markers are optional.
+
+    # method: HTTP request type such as GET or POST
+    # access: access restrictions such as FREE, RESTRICTED for paid subscribers, etc
+    # return: list of return data-formats like [JSON|XML] and what the return data means
+    # param: name and type of the parameter expected
+    # output: output format like JSON, XML. It is recommended that it should include an example of such data.
+    #         Each output marker must end with ::output-end:: on a separate line.
+    # request: a request generating code example
+    # response: a response processing code example
+
+You can define your own custom method markers as well.
+They will be available as the instance variables against which the _resource_method.html.erb template
+will be evaluated.
+
+Any other information that needs to be shown in the view can be specified in the apidoc comments as well.
+It will be shown under the "Description" section for the method in the view.
+
+
+B] Resource markers
+-------------------
+
+A resource, which is normally a controller object, can also be annotated with apidoc comments. 
+
+Method markers are specified the same way as the method markers:
+
+    # <<method-marker-name>:: <method-marker-value>
+    # 
+    # xml: xml representation of the resource
+    # json: json representation
+
+Just like in method marker, any other information that needs to be shown in the view can be specified in the apidoc comments as well.
+It will be shown under the "Description" section for the method in the view.
+
+
+C] Documentation Example
 ---------------------
 
     # =begin apidoc
     # url:: /books
     # method:: GET
@@ -61,16 +120,68 @@
     #::output-end::
     #
     # Get a list of all books in the system with pagination.  Defaults to 10 per page
     # =end
 
-    
-Layout
-------
 
-Documentation layout is located at `config/rapi_doc/layout.html.erb`.
 
+Haml Templates and styles
+=========================
+
+Resource and resource method annotations are available as instance and local variables in Haml templates.
+Here are the listing of variables available. But the best way to understand it is to look at the default 
+Haml templates generated by `rake rapi_doc:setup` in `config/rapi_doc` folder.
+
+
+A] Resource Method
+------------------
+
+    @resource_name: Resource name
+    @method_order: the numerical order of the method
+    @content: All Misc info
+    @url: url
+    @access: public/privileged, etc
+    @return: the data format of the info
+    @params: params expected by this api
+    @outputs: array of [output_format, output example], for example, [json, ....json output.. ]
+    @request: example of the data expected
+    @response: example of the response
+
+
+B] Resource
+-----------
+
+    @name: name
+    @xml: xml representation of the resource
+    @json: json representation
+    @function_blocks: Array of resource method objects described above
+
+
+    Following instance variables are only available in the index template described below (and not in the resource Haml template)
+    @resource_methods: Array of HTML generated for each of the methods. 
+    @resource_header: HTML generated for the resource
+
+
+C] Index
+--------
+
+    resource_docs: all the resource objects, whose instance variables are described above.
+    As mentioned before, for each resource, the HTML generated for the resource itself is available in @resource_header
+    and HTML generated for each of its methods is available in @resource_methods array. 
+
+
+
+D] Documentaton Output
+----------------------
+
+Documentation generated is located in `public/apidoc` directory.
+
+    index.html: contains the HTML 
+    styles.css: CSS styles
+    scripts.js: contains the script used to search within the documentation.
+
+
 Credit
 ======
 
 * Based on RAPI Doc by Jaap van der Meer found here: http://code.google.com/p/rapidoc/
-* https://github.com/sabman/rapi_doc
\ No newline at end of file
+* https://github.com/sabman/rapi_doc