useless-doc 0.6.5 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ba3662a9c3ab173c8820de546884c0bd66fb088e
-  data.tar.gz: 694e5e39110439e113372740c7ce0b7bf297825f
+  metadata.gz: 8ef1a097ee5d9addd33af7c1fe5c79364d438284
+  data.tar.gz: d85d7c813564eddc5718549d7c205684760f481a
 SHA512:
-  metadata.gz: 1f51ce037bc2fa57ad44a202a0db3debd8ce793d4d994e2f4a788b2e41b81f8718609a9b14a17b80a0758204d5acb84bac6cf300c5f7c2d73f1655686965b0b4
-  data.tar.gz: 9ce2dddf8b6deb173baa43cd8df40aa23b52498af3522f2d3e60a4b9e1f94b7553041416c169945fe88944159b2649ea8212cda6d374da1eb648d8b1bf501c97
+  metadata.gz: 4225d239755a926606513739e7ede9d92d4d289d1c6802cd0753429c434ae19f6a7d1e35812472ecf76c2c7d8ff315b23d0b6dabbc37d5c7ad98a516371b8053
+  data.tar.gz: 4a5273f15009e401bea7b39a8d672cf202ab7108f38a1fede74b48dd73bf7043070fda87420f3240246ebf56a259ae19a7a7b46344556a33f6fd50f5eae7dc3f

data/lib/useless/doc/core/body.rb

@@ -34,15 +34,21 @@ module Useless
         #
         # @!attribute [r] required
         #   @return [Boolean] whether or not the attribute is required. If it
-        #     is required, and the attribute is omitted, the response should have
-        #     a 4xx code. +true+ is the default value.
+        #     is required, and the attribute is omitted, the response should
+        #     have a 4xx code. +true+ is the default value.
         #
         # @!attribute [r] description
         #   @return [String] a description of the attribute.
         #
+        # @!attribute [r] attributes
+        #   @return [Array<Body::Attribute>] documentation for the
+        #     sub-attributes of this attribute. An empty array is the default
+        #     value.
+        #
         class Attribute
 
-          attr_reader :key, :type, :required, :default, :description
+          attr_reader :key, :type, :required, :default, :description,
+            :attributes
 
           # @param [Hash] attrs corresponds to the class's instance attributes.
           #
@@ -52,6 +58,7 @@ module Useless
             @required     = attrs.key?(:required) ? attrs[:required] : true
             @default      = attrs[:default]
             @description  = attrs[:description]
+            @attributes   = attrs[:attributes] || []
           end
         end
       end

data/lib/useless/doc/dsl.rb

@@ -325,8 +325,11 @@ module Useless
           @attributes[:content_type] = value
         end
 
-        def attribute(key, description, attributes = {})
-          attribute = Doc::Core::Body::Attribute.new attributes.merge(key: key, description: description)
+        def attribute(key, description, attributes = {}, &block)
+          subbody = Body.build({}, &block)
+          attribute = Doc::Core::Body::Attribute.new attributes.merge(
+            key: key, description: description, attributes: subbody.attributes
+          )
           @attributes[:attributes] << attribute
         end
       end

data/lib/useless/doc/serialization/dump.rb

@@ -156,7 +156,8 @@ module Useless
               'type' => attribute.type,
               'required' => attribute.required,
               'default' => attribute.default,
-              'description' => attribute.description
+              'description' => attribute.description,
+              'attributes' => attribute.attributes.map { |attribute| body_attribute(attribute) }
           end
         end
 

data/lib/useless/doc/serialization/load.rb

@@ -234,12 +234,17 @@ module Useless
         def self.body_attribute(json)
           hash = json_to_hash json
 
+          attributes = (hash['attributes'] || []).map do |json|
+            body_attribute json
+          end
+
           Useless::Doc::Core::Body::Attribute.new \
             key:          hash['key'],
             type:         hash['type'],
             required:     hash['required'],
             default:      hash['default'],
-            description:  hash['description']
+            description:  hash['description'],
+            attributes:   attributes
         end
       end
     end

data/lib/useless/doc/ui/godel.rb

@@ -175,7 +175,8 @@ module Useless
         class Response
           extend Forwardable
 
-          def_delegators :@response, :code, :description, :headers, :body
+          def_delegators :@response, :code, :description, :headers, :body,
+            :attributes
 
           def initialize(response)
             @response = response

data/lib/useless/doc/ui/godel/resource.mustache

@@ -96,6 +96,26 @@
                     <td>{{required}}</td>
                     <td>{{default}}</td>
                   </tr>
+
+                  {{#attributes}}
+                    <tr class="sub-attribute">
+                      <td>{{key}}</td>
+                      <td>{{description}}</td>
+                      <td>{{type}}</td>
+                      <td>{{required}}</td>
+                      <td>{{default}}</td>
+                    </tr>
+
+                    {{#attributes}}
+                      <tr class="sub-sub-attribute">
+                        <td>{{key}}</td>
+                        <td>{{description}}</td>
+                        <td>{{type}}</td>
+                        <td>{{required}}</td>
+                        <td>{{default}}</td>
+                      </tr>
+                    {{/attributes}}
+                  {{/attributes}}
                 {{/attributes}}
               </tbody>
             </table>
@@ -153,6 +173,26 @@
                         <td>{{required}}</td>
                         <td>{{default}}</td>
                       </tr>
+
+                      {{#attributes}}
+                        <tr class="sub-attribute">
+                          <td>{{key}}</td>
+                          <td>{{description}}</td>
+                          <td>{{type}}</td>
+                          <td>{{required}}</td>
+                          <td>{{default}}</td>
+                        </tr>
+
+                        {{#attributes}}
+                          <tr class="sub-sub-attribute">
+                            <td>{{key}}</td>
+                            <td>{{description}}</td>
+                            <td>{{type}}</td>
+                            <td>{{required}}</td>
+                            <td>{{default}}</td>
+                          </tr>
+                        {{/attributes}}
+                      {{/attributes}}
                     {{/attributes}}
                   </tbody>
                 </table>

data/lib/useless/doc/ui/godel/stylesheet.css

@@ -37,6 +37,10 @@ h3 span.status-message {
   font-weight: normal;
 }
 
+h4 {
+  font-size: 1.25em;
+}
+
 h4 span.content-type {
   font-weight: normal;
   font-family: 'Open Sans';
@@ -191,6 +195,22 @@ table tbody tr:last-child td, table tbody tr:last-child th {
   border-bottom-width: 0;
 }
 
+table tr.sub-attribute {
+  background-color: #EEE;
+}
+
+table tr.sub-attribute td:first-child {
+  padding-left: 1.5em;
+}
+
+table tr.sub-sub-attribute {
+  background-color: #DDD;
+}
+
+table tr.sub-sub-attribute td:first-child {
+  padding-left: 3em;
+}
+
 table.stages {
   margin-top: 2em;
 }

data/lib/useless/doc/version.rb

@@ -1,5 +1,5 @@
 module Useless
   module Doc
-    VERSION = '0.6.5'
+    VERSION = '0.7.0'
   end
 end

data/spec/documents/resource.json

@@ -48,7 +48,27 @@
                 "key": "created_by",
                 "type": "object",
                 "required": true,
-                "description": "The short name of the user who created the twonk."
+                "description": "The user who created this twonk.",
+                "attributes": [
+                  {
+                    "key": "id",
+                    "type": "number",
+                    "required": true,
+                    "description": "The unique ID of the user."
+                  },
+                  {
+                    "key": "short_name",
+                    "type": "string",
+                    "required": true,
+                    "description": "A user-friendly handle for the user."
+                  }
+                ]
+              },
+              {
+                "key": "title",
+                "type": "string",
+                "required": false,
+                "description": "The formal title of this twonk"
               }
             ]
           }

data/spec/useless/doc/dsl_spec.rb

@@ -62,6 +62,9 @@ describe Useless::Doc::DSL::API do
               attribute 'name', 'The name of the widget', required: true
               attribute 'age', 'The age of the widget. If missing, the widget was never born',
                 type: :number, required: false
+              attribute 'owner', 'The owner of this widget', type: 'object' do
+                attribute 'nickname', 'The nickname of the owner'
+              end
             end
           end
         end
@@ -110,6 +113,7 @@ describe Useless::Doc::DSL::API do
       collection.requests[0].method.should == 'GET'
       collection.requests[0].headers[0].description.should == 'The twiddle threshold.'
       collection.requests[0].responses[1].code.should == 200
+      collection.requests[0].responses[1].body.attributes[2].attributes[0].key.should == 'nickname'
       collection.requests[1].method.should == 'POST'
       collection.requests[1].description.should == 'Creates a new widget'
       collection.requests[1].body.content_type.should == 'application/json'

data/spec/useless/doc/serialization/dump_spec.rb

@@ -112,12 +112,20 @@ describe Useless::Doc::Serialization::Dump do
         key:          'Type',
         description:  'The response type.'
 
+      get_response_body_subattribute = Useless::Doc::Core::Body::Attribute.new \
+        key:          'nickname',
+        type:         'string',
+        required:     true,
+        default:      nil,
+        description:  'The nickname of the user'
+
       get_response_body_attribute = Useless::Doc::Core::Body::Attribute.new \
         key:          'name',
         type:         'string',
         required:     true,
         default:      nil,
-        description:  'The name of the twiddle.'
+        description:  'The name of the twiddle.',
+        attributes:   [get_response_body_subattribute]
 
       get_response_body = Useless::Doc::Core::Body.new \
         content_type: 'application/json',
@@ -193,6 +201,13 @@ describe Useless::Doc::Serialization::Dump do
       get_request_body_attribute_hash['required'].should == true
       get_request_body_attribute_hash['default'].should be_nil
       get_request_body_attribute_hash['description'].should == 'The name of the twiddle.'
+
+      get_request_body_subattribute_hash = Useless::Doc::Serialization::Load.json_to_hash(get_request_body_attribute_hash['attributes'][0])
+      get_request_body_subattribute_hash['key'].should == 'nickname'
+      get_request_body_subattribute_hash['type'].should == 'string'
+      get_request_body_subattribute_hash['required'].should == true
+      get_request_body_subattribute_hash['default'].should be_nil
+      get_request_body_subattribute_hash['description'].should == 'The nickname of the user'
     end
   end
 

data/spec/useless/doc/serialization/load_spec.rb

@@ -119,7 +119,9 @@ describe Useless::Doc::Serialization::Load do
       get.responses[1].body.attributes[1].type.should == 'object'
       get.responses[1].body.attributes[1].required.should be_true
       get.responses[1].body.attributes[1].default.should be_nil
-      get.responses[1].body.attributes[1].description.should == 'The short name of the user who created the twonk.'
+      get.responses[1].body.attributes[1].description.should == 'The user who created this twonk.'
+      get.responses[1].body.attributes[1].attributes[0].key.should == 'id'
+      get.responses[1].body.attributes[1].attributes[1].key.should == 'short_name'
 
       put = resource.requests.last
       put.method.should == 'PUT'

data/spec/useless/doc/ui/godel_spec.rb

@@ -188,7 +188,7 @@ describe Useless::Doc::UI::Godel do
       it 'should add body information to a table' do
         [
           { key: 'name', description: 'The name of the twonk.' },
-          { key: 'created_by', description: 'The short name of the user who created the twonk.' },
+          { key: 'created_by', description: 'The user who created this twonk.' },
           { key: 'hoinked_by', description: 'The ID of the person who hoinked this twonk.' }
         ].each do |attribute|
           @doc.css('table').find do |table|
@@ -198,6 +198,18 @@ describe Useless::Doc::UI::Godel do
         end
       end
 
+      it 'should add body sub-attributes to a special table row' do
+        [
+          { key: 'id', description: 'The unique ID of the user.' },
+          { key: 'short_name', description: 'A user-friendly handle for the user.' },
+        ].each do |attribute|
+          @doc.css('table tr.sub-attribute').find do |table|
+            table.content.match(attribute[:key]) and
+            table.content.match(attribute[:description])
+          end.should_not be_nil
+        end
+      end
+
       it 'should add header information to a table' do
         @doc.css('table').find do |table|
           table.content.match('User-Agent') and

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.6.5
+  version: 0.7.0
 platform: ruby
 authors:
 - Kevin Hyland
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-06 00:00:00.000000000 Z
+date: 2013-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj