useless-doc 0.5.0 → 0.6.0

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

@@ -19,9 +19,19 @@ module Useless
       # @!attribute [r] resources
       #   @return [Array<Resource>] the resources included in the API.
       #
+      # @!attribute [r] concept
+      #   @return [Stage] a `Core::Stage` instance for the API concept.
+      #
+      # @!attribute [r] specification
+      #   @return [Stage] a `Core::Stage` instance for the API specification.
+      #
+      # @!attribute [r] implementation
+      #   @return [Stage] a `Core::Stage` instance for the API implementation.
+      #
       class API
 
-        attr_accessor :name, :url, :description, :timestamp, :resources
+        attr_accessor :name, :url, :description, :timestamp, :resources,
+          :concept, :specification, :implementation
 
         # @param [Hash] attrs corresponds to the class's instance attributes.
         #
@@ -31,6 +41,9 @@ module Useless
           @description = attrs[:description]
           @timestamp = attrs[:timestamp]
           @resources = attrs[:resources] || []
+          @concept = attrs[:concept]
+          @specification = attrs[:specification]
+          @implementation = attrs[:implementation]
         end
       end
     end

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

@@ -0,0 +1,29 @@
+module Useless
+  module Doc
+    module Core
+
+      # `Core::Stage` documents credit and progress of a stage in the
+      # development of an API. For example, a stage is one of "concept",
+      # "specification" or "implementation" in `Core::API`.
+      #
+      # @!attribute [r] credit
+      #   @return [Array<String>] names of the people responsible for this 
+      #     stage.
+      #
+      # @!attribute [r] progress
+      #   @return [String] a string identifying how far the stage has
+      #     progressed.
+      #
+      class Stage
+        attr_accessor :credit, :progress
+
+        # @param [Hash] attrs corresponds to the class's instance attributes.
+        #
+        def initialize(attrs = {})
+          @credit = attrs[:credit] || []
+          @progress = attrs[:progress]
+        end
+      end
+    end
+  end
+end

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

@@ -48,7 +48,24 @@ module Useless
               'url' => api.url,
               'description' => api.description,
               'timestamp' => api.timestamp ? api.timestamp.iso8601 : nil,
-              'resources' => api.resources.map { |resource| resource(resource) }
+              'resources' => api.resources.map { |resource| resource(resource) },
+              'concept' => stage(api.concept),
+              'specification' => stage(api.specification),
+              'implementation' => stage(api.implementation)
+          end
+        end
+
+        # Converts +Core::Stage+ instance to a JSON representation.
+        #
+        # @param [Core::Stage] stage the stage to be converted to JSON.
+        #
+        # @return [String] a JSON representation of the specified stage.
+        #
+        def self.stage(stage)
+          if stage
+            hash_to_json \
+              'credit' => stage.credit,
+              'progress' => stage.progress
           end
         end
 

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

@@ -6,6 +6,7 @@ require 'useless/doc/core/header'
 require 'useless/doc/core/request'
 require 'useless/doc/core/resource'
 require 'useless/doc/core/response'
+require 'useless/doc/core/stage'
 
 module Useless
   module Doc
@@ -86,12 +87,43 @@ module Useless
             nil
           end
 
+          if hash['concept']
+            concept = stage hash['concept']
+          end
+
+          if hash['specification']
+            specification = stage hash['specification']
+          end
+
+          if hash['implementation']
+            implementation = stage hash['implementation']
+          end
+
           Useless::Doc::Core::API.new \
-            name:         hash['name'], 
-            url:          hash['url'],
-            timestamp:    timestamp,
-            description:  hash['description'],
-            resources:    resources
+            name:           hash['name'], 
+            url:            hash['url'],
+            timestamp:      timestamp,
+            description:    hash['description'],
+            resources:      resources,
+            concept:        concept,
+            specification:  specification,
+            implementation: implementation
+        end
+
+        # Converts a JSON representation to an instance of +Core::Stage+
+        #
+        # @param [String, Hash] json the JSON representation to be converted to
+        #   a stage.
+        #
+        # @return [Core::Resource] the stage corresponding to the specified
+        #   JSON.
+        #
+        def self.stage(json)
+          hash = json_to_hash json
+
+          Useless::Doc::Core::Stage.new \
+            credit:   hash['credit'],
+            progress: hash['progress']
         end
 
         # Converts a JSON represntation to an instance of +Core::Resource+

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

@@ -32,6 +32,45 @@
   <section class="main description">
     <article class="description api">
       {{{description}}}
+
+      <table class="stages">
+        <thead>
+          <th>Specification</th>
+          <th>Implementation</th>
+          <th>Concept</th>
+        <tbody>
+          <tr>
+            <td>
+              {{#specification}}
+                {{progress}}
+              {{/specification}}
+            </td>
+            <td>
+              {{#implementation}}
+                {{progress}}
+              {{/implementation}}
+            </td>
+            <td class="concept-credit" rowspan=2>
+              {{#concept}}
+                {{credit}}
+              {{/concept}}
+            </td>
+          </tr>
+
+          <tr>
+            <td>
+              {{#specification}}
+                {{credit}}
+              {{/specification}}
+            </td>
+            <td class="implementation-credit">
+              {{#implementation}}
+                {{credit}}
+              {{/implementation}}
+            </td>
+          </tr>
+        </tbody>
+      </table>
     </article>
   </section>
 

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

@@ -163,3 +163,19 @@ table td:last-child, table th:last-child {
 table tbody tr:last-child td, table tbody tr:last-child th {
   border-bottom-width: 0;
 }
+
+table.stages {
+  margin-top: 2em;
+}
+
+table.stages td, table.stages th {
+  padding: 0.5em 1em;
+}
+
+table.stages td.implementation-credit {
+  border-right: 1px solid #DDD;
+}
+
+table.stages td.concept-credit {
+  border-bottom-width: 0;
+}

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

@@ -89,6 +89,24 @@ module Useless
           def resources
             @api.resources.map{ |resource| Godel::Resource.new(resource, @router) }
           end
+
+          def concept
+            if @api.concept
+              Godel::Stage.new(@api.concept)
+            end
+          end
+
+          def specification
+            if @api.specification
+              Godel::Stage.new(@api.specification)
+            end
+          end
+
+          def implementation
+            if @api.implementation
+              Godel::Stage.new(@api.implementation)
+            end
+          end
         end
 
         class Resource < Mustache
@@ -160,6 +178,23 @@ module Useless
             headers.any?
           end
         end
+
+        class Stage
+          def initialize(stage)
+            @stage = stage
+          end
+
+          def progress
+            @stage.progress.
+              split('-').
+              map { |word| word.capitalize }.
+              join(' ')
+          end
+
+          def credit
+            @stage.credit.join(', ')
+          end
+        end
       end
     end
   end

data/lib/useless/doc/version.rb

@@ -1,5 +1,5 @@
 module Useless
   module Doc
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

data/spec/documents/api.json

@@ -3,6 +3,18 @@
   "url": "twonk.useless.io",
   "timestamp": "2013-03-06T23:13:00-05:00",
   "description": "Twonk information. Duh.",
+  "concept": {
+    "credit": ["John Henry"],
+    "progress": "complete"
+  },
+  "specification": {
+    "credit": ["Bill Wever"],
+    "progress": "in-progress"
+  },
+  "implementation": {
+    "credit": ["Bill Wever", "John Henry"],
+    "progress": "pending"
+  },
   "resources": [
     {
       "path": "/twonks/:id",

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

@@ -7,6 +7,7 @@ require 'useless/doc/core/header'
 require 'useless/doc/core/request'
 require 'useless/doc/core/resource'
 require 'useless/doc/core/response'
+require 'useless/doc/core/stage'
 require 'useless/doc/serialization/dump'
 require 'useless/doc/serialization/load'
 
@@ -53,6 +54,18 @@ describe Useless::Doc::Serialization::Dump do
 
   describe '.api' do
     it 'should convert the specified Core::API instance to JSON' do
+      concept = Useless::Doc::Core::Stage.new \
+        credit: ['Joe Blue'],
+        progress: 'complete'
+
+      specification = Useless::Doc::Core::Stage.new \
+        credit: ['Bill Grey'],
+        progress: 'in-progress'
+
+      implementation = Useless::Doc::Core::Stage.new \
+        credit: ['Bill Grey', 'Joe Blue'],
+        progress: 'pending'
+
       resource = Useless::Doc::Core::Resource.new \
         path:         '/twiddles',
         description:  'The full lot of twiddles.',
@@ -63,7 +76,10 @@ describe Useless::Doc::Serialization::Dump do
         url: 'twiddles.useless.io',
         timestamp: Time.parse('2013-03-06 11:13 PM'),
         description: 'Pretty much, like, everything you\'re looking for',
-        resources: [resource]
+        resources: [resource],
+        concept: concept,
+        specification: specification,
+        implementation: implementation
 
       json = Useless::Doc::Serialization::Dump.api(api)
       hash = Useless::Doc::Serialization::Load.json_to_hash(json)
@@ -72,6 +88,18 @@ describe Useless::Doc::Serialization::Dump do
       hash['timestamp'].should == Time.parse('2013-03-06 11:13 PM').iso8601
       hash['description'].should == 'Pretty much, like, everything you\'re looking for'
 
+      concept_hash = Useless::Doc.load.json_to_hash(hash['concept'])
+      concept_hash['credit'].should == ['Joe Blue']
+      concept_hash['progress'].should == 'complete'
+
+      specification_hash = Useless::Doc.load.json_to_hash(hash['specification'])
+      specification_hash['credit'].should == ['Bill Grey']
+      specification_hash['progress'].should == 'in-progress'
+
+      implementation_hash = Useless::Doc.load.json_to_hash(hash['implementation'])
+      implementation_hash['credit'].should == ['Bill Grey', 'Joe Blue']
+      implementation_hash['progress'].should == 'pending'
+
       resource_hash = Useless::Doc::Serialization::Load.json_to_hash(hash['resources'][0])
       resource_hash['path'].should == '/twiddles'
       resource_hash['description'].should == 'The full lot of twiddles.'

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

@@ -61,6 +61,12 @@ describe Useless::Doc::Serialization::Load do
       api.url.should == 'twonk.useless.io'
       api.timestamp.should == Time.parse('2013-03-06T23:13:00-05:00')
       api.description.should == 'Twonk information. Duh.'
+      api.concept.credit.should == ['John Henry']
+      api.concept.progress.should == 'complete'
+      api.specification.credit.should == ['Bill Wever']
+      api.specification.progress.should == 'in-progress'
+      api.implementation.credit.should == ['Bill Wever', 'John Henry']
+      api.implementation.progress.should == 'pending'
       api.resources.first.path.should == '/twonks/:id'
       api.resources.first.description.should == 'The most critical aspect.'
     end

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

@@ -114,6 +114,26 @@ describe Useless::Doc::UI::Godel do
         as.find { |a| a.content == 'POST' }['href'].should == '/twonks/:id/werp#POST'
         td_content.should include 'Make dem werps.'
       end
+
+      it 'should display concept information' do
+        stages = @doc.css('table.stages').first.content
+        stages.should include 'Concept'
+        stages.should include 'John Henry'
+      end
+
+      it 'should display specification information' do
+        stages = @doc.css('table.stages').first.content
+        stages.should include 'Specification'
+        stages.should include 'Bill Wever'
+        stages.should include 'In Progress'
+      end
+
+      it 'should display implementation information' do
+        stages = @doc.css('table.stages').first.content
+        stages.should include 'Implementation'
+        stages.should include 'Bill Wever, John Henry'
+        stages.should include 'Pending'
+      end
     end
 
     context 'for a Core::Resource instance' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: useless-doc
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-08 00:00:00.000000000 Z
+date: 2013-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -192,6 +192,7 @@ files:
 - lib/useless/doc/core/request.rb
 - lib/useless/doc/core/resource.rb
 - lib/useless/doc/core/response.rb
+- lib/useless/doc/core/stage.rb
 - lib/useless/doc/dsl.rb
 - lib/useless/doc/proxy.rb
 - lib/useless/doc/proxy/css.rb