api_doc_generation 0.4.0 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81d519ebc01140cc7b74d66069a3b6eb3f8a07c7
-  data.tar.gz: 47b6f328b09fc166044e4236ee927890d8527691
+  metadata.gz: dc466cb2612dc05d4675097c536b541a3c1c74a6
+  data.tar.gz: 40f6398342e3aa43b3aaa443ed686b751c13b3ab
 SHA512:
-  metadata.gz: 06f370284d952468cf80dd44eeb0854264310913aacc96a7a9b80dd7d3dd755331252fe83906968320ce34662743a38b669704064fa9f5ce9f0dcfbbc0d6f800
-  data.tar.gz: ea5d24152928832e48c56e6406cb89b70928b30e94247afe10c5a2c4cac9a005b1271d8878953b99b951b606adf065c812c2525c92eecc2c933aef7d28341a20
+  metadata.gz: 0011170b68b8d86def142ac90396720bae4174ec8a72a31f9648e896b681f09e8b97b12c9fa5c2570167862c896ec23408a5a00e1820875096cb22dc5dfc2458
+  data.tar.gz: 7d6d9cf957b5c7b13e76b642416781138b390c70bd27feb5ad66e32d5d56622a965d174b0870ef64f773ce42d599297a4a33c107182abc8af57ebf1a2d9f724c

data/README.md

@@ -18,13 +18,22 @@ Or install it yourself as:
 
 ## Usage
 
-`rake doc:api [CODES_PATH=app/controllers/api] [OUT_FORMAT=simple_html|detailed_html]`
+`rake doc:api [opts=xxx]`
 
-__代码注释格式:__
+__参数说明:__
 
-```
+  * CODES_PATH
+    指定生成代码路径，默认为app/controllers/api
+  * OUT_FORMAT
+    simple_html 或者 detailed_html， 默认使用detailed_html 模板
+  * SHOW_BASE
+    是否为*BaseController结尾的controller生成文档，默认为false
 
-  # About: 文件说明
+__代码注释格式:__
+d
+
+  # 文件说明
+  # About: xxxx
   # Host: 定义api host
   # Other: ...
   class Api::UsersController < class Api::BaseController
@@ -74,19 +83,22 @@ __代码注释格式:__
 
 __总的来说，注释格式有三种__
 
-1.
+1. 只一层
+
 ```
 # 层级1: 说明
 ```
 
-2.
+2. 两层
+
 ```
 # 层级1:
 #   层级2: 说明
 #   层级2: 说明
 ```
 
-3.
+3. 超过两层
+
 ```
 # 层级1:
 #   层级2: 说明
@@ -108,6 +120,13 @@ __总的来说，注释格式有三种__
 
 
 
+## 注意
+为加强文档规范化，以下情况的controller将不再生成显示出来：
+
+1. 当前Controller没有文件说明
+2. 当前controller的actions数量为0
+3. 当前action没有Return说明
+
 ## Contributing
 
 1. Fork it

data/lib/api_doc_generation/format_file.rb

@@ -8,6 +8,7 @@ module ApiDocGeneration; module FormatFile; class << self
     klass = class_name.safe_constantize
     filelines = File.readlines(path)
     actions = klass.action_methods - klass.superclass.action_methods
+    ctrl_about = get_controller_about(filelines, klass.to_s)
 
     actions = actions.map do |action|
       method = klass.instance_method action
@@ -16,7 +17,13 @@ module ApiDocGeneration; module FormatFile; class << self
       note = FormatNote.analyze(filelines, line - 2)
       note["Level"] ||= ''
       note['Name'] = action.to_s
-      note = get_routes(klass, action).merge(note) unless note['Path']
+
+      unless note['Path']
+        note = get_routes(klass, action).merge(note)
+      else
+        note['Path'] = note['Path'][0]['desc'] 
+        note['Method'] = note['Method'][0]['desc'] rescue nil
+      end
 
       note
     end
@@ -25,11 +32,10 @@ module ApiDocGeneration; module FormatFile; class << self
       val['Return'].nil?
     end
     
-
     {
       'Path' => path,
       'Klass' => klass.to_s,
-      'About' => get_controller_about(filelines, klass.to_s),
+      'About' => ctrl_about,
       'Actions' => actions
     }
   end

data/lib/api_doc_generation/generation.rb

@@ -7,13 +7,17 @@ require 'api_doc_generation/format_note'
 module ApiDocGeneration; class Generation
   attr_reader :controller_documents
 
-  def initialize(codes_path = nil, title = '')
+  def initialize(codes_path = nil, title = '', opts = {})
     codes_path ||= File.expand_path('app/controllers/api', Rails.root)
     @controller_documents = []
     @title = title
+    @opts = opts
 
     each_api_controllers_file(codes_path) do |path|
-      @controller_documents << FormatFile.analyze_file(path)
+      ctrl_doc = FormatFile.analyze_file(path)
+      next if ctrl_doc['About']['Desc'].nil? || ctrl_doc['About']['Desc'].length == 0
+      next if ctrl_doc['Actions'].length == 0
+      @controller_documents << ctrl_doc
     end
   end
 
@@ -45,7 +49,7 @@ module ApiDocGeneration; class Generation
   def each_api_controllers_file(codes_path, &block)
     paths = codes_path.end_with?('.rb') ? [codes_path] : Dir[codes_path + '/**/*.rb']
     paths.each do |path|
-      next if path =~ /base_controller.*\.rb$/
+      next if path =~ /base_controller.*\.rb$/ && @opts[:show_base] != true
       block.call path
     end
   end

data/lib/api_doc_generation/version.rb

@@ -1,3 +1,3 @@
 module ApiDocGeneration
-  VERSION = "0.4.0"
+  VERSION = "0.4.3"
 end

data/lib/rake/tasks/api_doc.rake

@@ -9,7 +9,9 @@ namespace :doc do
     title = ENV['TITLE']
 
     puts "Template: #{out_format}"
-    generation = ApiDocGeneration::Generation.new(codes_path, title)
+    generation = ApiDocGeneration::Generation.new(codes_path, title, {
+      :show_base => ENV['SHOW_BASE'].to_s == 'true' ? true : false
+    })
 
     puts generation.controller_documents if ENV['SHOW_DOCS']
     

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api_doc_generation
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.3
 platform: ruby
 authors:
 - jiangzhi.xie
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-23 00:00:00.000000000 Z
+date: 2013-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler