acu111376 - Add '@recipe' tag for detailed recipe descriptions (Fixes…

… Issue #8)

README.md

@@ -27,7 +27,7 @@ If you are using Ruby 1.8.x, you need to install Ripper as well:
 ### Cookbook README
 The cookbook README file included in your cookbooks will be the landing page for
 each cookbook.  Under this verbatim inclusion of your README will be a
-```Cookbook Documentation``` section that contains the auto-generated information
+`Cookbook Documentation` section that contains the auto-generated information
 
 ### Cookbook Metadata
 This plugin grabs most of it's information from the cookbook metadata.rb file.
@@ -38,7 +38,7 @@ The rest of the stuff is parsed from cookbook code itself.
 
 ### YARD-Chef Tags
 We also need a way to link your providers to their resources.  To do so add a
-``` @resource <resource_name>``` tag in each of your provider code.  This tag
+` @resource <resource_name>` tag in each of your provider code.  This tag
 should be in a comment separated from other comments, for example:
 
     # This is my super_cool provider
@@ -49,6 +49,19 @@ should be in a comment separated from other comments, for example:
     # Here is the first action
     ...
 
+We can add more description to a recipe (besides `metadata.rb`) in the recipe file
+using `@recipe` tag as follows
+
+    # This is my recipe
+    #
+    # @recipe <<-EOF
+    # This is a detailed description for my recipe.
+    # This does a lot of things.
+    # EOF
+    #
+    ...
+
+
 ### Standard YARD Tags and Comments
 Your definitions, libraries, resources and providers can benefit from
 adding YARD tags and comments for each class and method.  You can learn more about the tags from
@@ -100,7 +113,7 @@ Then just run
     rake yard
 
 ### Command-line
-From the root of your cookbook repository, run the ```yardoc``` command to
+From the root of your cookbook repository, run the `yardoc` command to
 generate documentation using the following command
 
     yardoc '**/*.rb' --plugin chef
@@ -115,7 +128,7 @@ generated ./doc directory.  Once there run:
 
     yard server --reload -B localhost -p 8000 --plugin yard-chef
 
-Add a ```-d``` option flag to run the server in daemon mode.  For more
+Add a `-d` option flag to run the server in daemon mode.  For more
 information about YARD server see [http://yardoc.org/](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#yard_Executable)
 
 ## License

lib/yard-chef.rb

@@ -58,15 +58,14 @@ module YARD::CodeObjects::Chef
 
         recipe.source = IO.read(file)
         recipe.add_file(file, 1)
+
+        recipe.add_long_desc(file)
       end
     end
   end
 
-  # Register '@resource' tag for mapping providers with light-weight resources
-  YARD::Tags::Library.define_tag(
-    'Map Chef Providers with Chef Resources',
-    :resource
-  )
+  YARD::Tags::Library.define_tag('Map Chef Providers with Chef Resources', :resource)
+  YARD::Tags::Library.define_tag('Detailed description for recipes', :recipe)
 
   # Register template directory for the chef plugin
   template_dir = File.expand_path('../templates', File.dirname(__FILE__))

lib/yard-chef/code_objects/recipe_object.rb

@@ -29,6 +29,8 @@ module Chef
     class RecipeObject < ChefObject
       register_element :recipe
 
+      attr_accessor :long_desc
+
       # Creates a new instance of RecipeObject.
       #
       # @param namespace [NamespaceObject] namespace to which the recipe belongs
@@ -38,6 +40,7 @@ class RecipeObject < ChefObject
       #
       def initialize(namespace, name)
         super(namespace, name)
+        @long_desc = ""
       end
 
       # Prefixes recipe name with the name of the cookbook.
@@ -47,6 +50,28 @@ def initialize(namespace, name)
       def name
         self.parent.name.to_s << '::' << @name.to_s
       end
+
+      # Parses detailed recipe description within the recipe file mentioned by
+      # '@recipe' tag.
+      #
+      # @param recipe_file [String] the recipe file
+      #
+      def add_long_desc(recipe_file)
+        file = File.open(recipe_file, 'r')
+        heredoc = nil
+        file.readlines.each do |line|
+          if line =~ /#\s@recipe\s<<-?\s?(\w+)/
+            heredoc = $1
+            next
+          end
+
+          if heredoc
+            line = line.sub(/^\s*#\s*/,'')
+            break if line =~ /#{heredoc}/
+            @long_desc << line
+          end
+        end
+      end
     end
   end
 end

templates/default/recipe/html/recipe_list.erb

@@ -30,7 +30,11 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
       <h3 class="signature"><a name="<%= recipe.name %>">
         <strong><%= recipe.name %></strong>
       </a></h3>
-      <%= htmlify recipe.docstring %>
+      <% if recipe.long_desc.empty? %>
+        <%= htmlify recipe.docstring %>
+      <% else %>
+        <%= htmlify recipe.long_desc %>
+      <% end %>
       <%= yieldall :object => recipe, :owner => object, :index => i %>
     </div>
   <% end %>