Minor doc updates plus lots of XXX where clarifications are needed

1 files changed, 32 insertions, 6 deletions

diff --git a/spec/spore_description.pod b/spec/spore_description.pod
index f0433e5..5d921a9 100644
--- a/spec/spore_description.pod
+++ b/spec/spore_description.pod
@@ -42,6 +42,9 @@ create a programmatic interface in the target system.
 An API should provide a description file. The description should be in JSON
 format.
 
+XXX all the example should be changes to use valid json fragments instead of yaml.
+I've noted the obvious cases (lists) but the others also need changing to add double quotes etc.
+
 =head2 GENERIC DESCRIPTION
 
 This part describes the API itself:
@@ -61,12 +64,16 @@ A list of authors for this specification
     author:
       - franck cuny <franck@lumberjaph.net>
 
+XXX yaml remnant. should it be an json array? can it be a simple string?
+
 =item B<api_base_url> (optional)
 
 If the API has a fixed URL
 
     api_base_url: http://api.twitter.com/1/
 
+XXX should it end with "/"? twitter.json doesn't.
+
 =item B<api_format> (optional)
 
 A list of supported format
@@ -75,12 +82,16 @@ A list of supported format
       - json
       - xml
 
+XXX what does "supported format" actually mean? What's the effect? Is it really a list?
+
 =item B<version> (optinal)
 
 The version number of the current description
 
     version: 0.1
 
+XXX clarify type (string/numeric). twitter.json has a string. Any semantics or just for documentation?
+
 =item B<authentication> (optional)
 
 A boolean to specify if this API requires authentication for all the methods
@@ -91,13 +102,15 @@ A boolean to specify if this API requires authentication for all the methods
 
 A list of methods
 
+XXX list? twitter.json has a hash
+
 =back
 
 The desciption B<MUST> contain a list of at least one method
 
 =head2 METHOD DESCRIPTION
 
-A method must have a name:
+A method must have a name, which is the key of the C<methods> hash described above:
 
     public_timeline
 
@@ -111,20 +124,26 @@ An HTTP method
 
 =item B<path> (required)
 
-Path for the given method. The path can contain B<placeholders>. A placeholder
+Path for the given method. The path can contain I<placeholders>. A placeholder
 B<MUST> begin with a <:>:
 
     path: /statuses/public_timeline.:format
 
+XXX How can non-placeholder :foo's be included in the path? ie is there an escape mechanism?
+What happens in this example if 'format' isn't listed in params?
+
 =item B<params> (optional)
 
-A list of parameters. This list will be used to replace value in placeholders,
+A list of optional parameters (also see C<required> below).
+This list will be used to replace value in placeholders,
 and if not used in the path, will be added to the query
 
     params:
       - trim_user
       - include_entities
 
+XXX yaml
+
 =item B<required> (optional)
 
 A list of required parameters. Parameters that are required B<MUST NOT> be
@@ -133,6 +152,8 @@ repeated in the B<params> field
     required:
       - format
 
+XXX yaml
+
 =item B<expected> (optional)
 
 A list of accepted HTTP status for this method
@@ -140,6 +161,9 @@ A list of accepted HTTP status for this method
     expected:
       - 200
 
+XXX what are the semantics of this? ie does it mean that an exception will be
+thrown if some other status is returned?
+
 =item B<description> (optional)
 
 A simple description for the method. This should not be considered as
@@ -157,13 +181,15 @@ A boolean to specify if this method requires authentication
 
 Specify an url if this method requires a different api_base_url
 
-    api_base_url: http://api.twitter.com/1/
+    base_url: http://api.twitter.com/1/
+
+XXX trailing slash?
 
 =item B<format> (optional)
 
-A list of supported format
+A list of supported formats for this method, if different to C<api_format>:
 
-    api_format:
+    format:
       - json
       - xml