Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Changeset 8971

Show
Ignore:
Timestamp:
03/02/08 11:19:34 (2 months ago)
Author:
tobie
Message:

pdoc: Remove usage of class_eval to enable easier documentation by rdoc. Start documenting the code.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • spinoffs/pdoc/trunk/CHANGELOG

    r8967 r8971  
     1* Remove usage of class_eval to enable easier documentation by rdoc. Start documenting the code. [Tobie] 
     2 
    13* Add Treetop compiler rake task. [Tobie] 
    24 

  • spinoffs/pdoc/trunk/lib/pdoc/generators/html/page.rb

    r8963 r8971  
    1414        end 
    1515         
     16        # Renders the page as a string using the assigned layout. 
    1617        def render 
    1718          if @layout 
    …… 
    2324        end 
    2425         
     26        # Creates a new file and renders the page to it 
     27        # using the assigned layout. 
    2528        def render_to_file(filename) 
    2629          File.open(filename, "w+") do |f| 
    …… 
    2932        end 
    3033         
     34        # Web page's title 
    3135        def title 
    3236          "" 
    …… 
    5054        end 
    5155         
     56        # Web page's title 
    5257        def title 
    5358          " | #{@doc_instance.full_name} #{@doc_instance.type}" 

  • spinoffs/pdoc/trunk/lib/pdoc/generators/html/website.rb

    r8945 r8971  
    2929        end 
    3030         
     31        # Copies the the content of assets folder to the generated website's 
     32        # root directory. 
    3133        def copy_assets 
    3234          cp_r Dir.glob(File.join(TEMPLATES_DIR, "html", "assets", "**")), '.' 
    3335        end 
    3436         
     37        # Creates a new directory with read, write and execute permission. 
    3538        def mkdir(name) 
    3639          Dir.mkdir(name, 0755) 

  • spinoffs/pdoc/trunk/lib/pdoc/parser.rb

    r8967 r8971  
    1212module PDoc 
    1313  class Parser 
    14     include Documentation 
    1514    def initialize(string) 
    1615      @string = string 
    1716      @parser = DocumentationParser.new 
    18       pre_process 
    1917    end 
    2018     
     19    # Parses the preprocessed string. Returns an instance 
     20    # of Documentation::Doc 
    2121    def parse 
    22       @parser.parse(@template) 
     22      @parser.parse(pre_process) 
    2323    end 
    2424     
     25    # Preprocess the string before parsing. 
     26    # Converts "\r\n" to "\n" and avoids edge case 
     27    # by wrapping the string in line breaks. 
    2528    def pre_process 
    26       @template = "\n" << @string.gsub(/\r\n/, "\n") << "\n" 
     29      "\n" << @string.gsub(/\r\n/, "\n") << "\n" 
    2730    end 
    2831  end 

  • spinoffs/pdoc/trunk/lib/pdoc/parser/documentation_nodes.rb

    r8960 r8971  
    77    end 
    88     
     9    # Returns an array of all deprecated object. 
    910    def deprecated 
    1011      select{|e| e.deprecated? } 
    1112    end 
    1213     
     14    # Returns an array of all documented aliases. 
    1315    def aliases 
    1416      select{|e| e.alias? } 
    1517    end 
    16  
    17     %w(klass_method instance_method constructor constant 
    18     namespace klass_property instance_property utility mixin).each do |name| 
    19       class_name = name.split('_').map{|n| n.capitalize }.join 
    20       name = name.match(/y$/) ? "#{name.chop}ies" : "#{name}s" 
    21       src = <<-END_SRC 
    22         def #{name} 
    23           select{|e| e.is_a?(#{class_name}) } 
    24         end 
    25       END_SRC 
    26       class_eval src, __FILE__, __LINE__ 
    27     end 
    28      
     18     
     19    # return an array of all documented KlassMethod instances. 
     20    def klass_methods 
     21      select { |e| e.is_a?(KlassMethod) } 
     22    end 
     23 
     24    # return an array of all documented InstanceMethod instances. 
     25    def instance_methods 
     26      select { |e| e.is_a?(InstanceMethod) } 
     27    end 
     28 
     29    # return an array of all documented Constructor instances. 
     30    def constructors 
     31      select { |e| e.is_a?(Constructor) } 
     32    end 
     33 
     34    # return an array of all documented Constant instances. 
     35    def constants 
     36      select { |e| e.is_a?(Constant) } 
     37    end 
     38 
     39    # return an array of all documented Namespace instances. 
     40    def namespaces 
     41      select { |e| e.is_a?(Namespace) } 
     42    end 
     43 
     44    # return an array of all documented KlassProperty instances. 
     45    def klass_properties 
     46      select { |e| e.is_a?(KlassProperty) } 
     47    end 
     48 
     49    # return an array of all documented InstanceProperty instances. 
     50    def instance_properties 
     51      select { |e| e.is_a?(InstanceProperty) } 
     52    end 
     53 
     54    # return an array of all documented Utility instances. 
     55    def utilities 
     56      select { |e| e.is_a?(Utility) } 
     57    end 
     58 
     59    # return an array of all documented Mixin instances. 
     60    def mixins 
     61      select { |e| e.is_a?(Mixin) } 
     62    end 
     63     
     64    # return an array of all documented Klass instances. 
    2965    def klasses 
    30       select{|e| e.is_a?(Klass) } 
    31     end 
    32      
     66      select { |e| e.is_a?(Klass) } 
     67    end 
     68     
     69    # find_by_name allows you to search through all the documented instances based on the  
     70    # instances Base#full_name. 
     71    # For example: 
     72    # 
     73    #     PDoc::Parser.new("prototype.js").parse.root.find_by_name("Element#update") 
     74    # 
     75    # Return an instance of InstanceMethod corresponding to "Element#update". 
    3376    def find_by_name(name) 
    34       find{|e| e.full_name == name } 
     77      find { |e| e.full_name == name } 
    3578    end 
    3679     
    3780    def descendants 
    38       select{ |e| e.is_a?(Namespace) || e.is_a?(Utility) } 
    39     end 
    40      
     81      select { |e| e.is_a?(Namespace) || e.is_a?(Utility) } 
     82    end 
     83     
     84    # Returns an array of all documented instances which are global variables. 
    4185    def globals 
    4286      select{ |e| e.global? }.sort_by {|e| e.name } 
    …… 
    4488    alias children globals 
    4589     
     90    # Returns an array of all documented Section instances. 
    4691    def sections 
    4792      select{ |e| e.is_a?(Section) }.sort_by {|e| e.name } 
    …… 
    5297    end 
    5398     
     99    # Returns the total number of documented instances 
    54100    def size 
    55101      to_a.length 
    …… 
    58104   
    59105  class Base < Treetop::Runtime::SyntaxNode 
     106    # Returns an instance of Doc (the root of the tree outputed by the PDoc::Parser). 
    60107    def root 
    61108      parent.parent.parent 
    62109    end 
    63110     
     111    # True if the instance was tagged as deprecated. 
    64112    def deprecated? 
    65113      tags.include?("deprecated") || ancestors.any?{ |a| a.deprecated? } 
    66114    end 
    67115     
     116    # True if the instance is a global variable. 
    68117    def global? 
    69118      namespace_string.empty? 
    70119    end 
    71120     
     121    # True if the instance is an alias. 
    72122    def alias? 
    73123      tags.include?("alias of") 
    74124    end 
    75125     
     126    # If instance is tagged as an alias, alias_of returns the corresponding object. 
     127    # It will return nil otherwise. 
    76128    def alias_of 
    77129      if alias? 
    …… 
    83135    end 
    84136     
     137    # Returns an array of all aliases of this instance. 
    85138    def aliases 
    86139      root.select{ |a| a.alias_of == self } 
    87140    end 
    88141     
     142    # Returns an instance of Tags::Tags. 
    89143    def tags 
    90144      start.elements.last.empty? ? [] : start.elements.last 
    91145    end 
    92146     
    93     %w(klass_name name full_name).each do |name| 
    94       src = <<-END_SRC 
    95         def #{name} 
    96           ebnf.#{name} 
    97         end 
    98       END_SRC 
    99       class_eval src, __FILE__, __LINE__ 
    100     end 
    101  
     147    # Returns the instance's class name. 
     148    def klass_name 
     149      ebnf.klass_name 
     150    end 
     151     
     152    # Returns the instance's name. For example: 
     153    #     root.find_by_name("Element#update").name 
     154    #     # -> "update" 
     155    def name 
     156      ebnf.name 
     157    end 
     158     
     159    # Returns the instance's full_name. For example: 
     160    #     root.find_by_name("Element#update").full_name 
     161    #     # -> "Element#update" 
     162    def full_name 
     163      ebnf.full_name 
     164    end 
     165     
     166    # Returns the instance's namespace_string. Note that event if the instance is an method or property, 
     167    # the klass_name is not included in that string. So for example: 
     168    # 
     169    #     root.find_by_name("Ajax.Request#request").namespace_string 
     170    #     # -> "Ajax" 
    102171    def namespace_string 
    103172      ebnf.namespace 
    104173    end 
    105174     
     175    # Returns the section this instance belongs to. If no section has been  
     176    # specified in the tags, it iterates through the ancestors until it finds one. 
    106177    def section 
    107178      if tags.include?("section") 
    …… 
    113184    end 
    114185     
     186    # Returns the Klass instance if object is a class, nil otherwise. 
    115187    def klass 
    116188      nil 
    117189    end 
    118190     
     191    # Returns the instance's closests namespace or nil when instance or instance's 
     192    # Klass is a global. 
    119193    def namespace 
    120194      namespace_string.empty? ? nil : root.find_by_name(namespace_string) 
    121195    end 
    122196     
     197    # If instance is a global, returns its Section. Else its Namespace. 
    123198    def doc_parent 
    124199      namespace ? namespace : section 
    125200    end 
    126201     
     202    # Recursively collects all of instance's doc_parent and returns them 
     203    # as an ordered array. 
    127204    def ancestors 
    128205      [doc_parent].concat(doc_parent.ancestors) 
    129206    end 
    130207     
     208    # Returns all direct descendants of instance. 
    131209    def children 
    132210      root.descendants.select{|d| d.namespace === self }.sort_by {|e| e.name } 
    133211    end 
    134212     
     213    # Returns all descendants of instance. 
    135214    def descendants 
    136215      results = children 
    …… 
    153232   
    154233  class Section < Base 
    155     %w(name id full_name title description text).each do |name| 
    156       src = <<-END_SRC 
    157         def #{name} 
    158           section.#{name} 
    159         end 
    160       END_SRC 
    161       class_eval src, __FILE__, __LINE__ 
    162     end 
    163      
     234    # Returns section's name 
     235    def name 
     236      section.name 
     237    end 
     238 
     239    # Returns section's id 
     240    def id 
     241      section.id 
     242    end 
     243 
     244    # Returns section's full_name 
     245    def full_name 
     246      section.full_name 
     247    end 
     248 
     249    # Returns section's title 
     250    def title 
     251      section.title 
     252    end 
     253 
     254    # Returns section's description 
     255    def description 
     256      section.description 
     257    end 
     258 
     259    # Returns section's text 
     260    def text 
     261      section.text 
     262    end 
     263     
     264    # Returns nil. 
    164265    def klass_name 
    165266      nil 
    166267    end 
    167268     
     269    # Returns false. 
    168270    def global? 
    169271      false 
    170272    end 
    171273     
     274    # Returns nil. 
    172275    def namespace 
    173276      nil 
    174277    end 
    175278     
     279    # Returns an empty string. 
    176280    def namespace_string 
    177281      "" 
    178282    end 
    179283     
     284    # Returns nil. 
    180285    def section 
    181286      nil 
    182287    end 
    183288     
     289    # Returns nil. 
    184290    def doc_parent 
    185291      nil 
    186292    end 
    187293     
     294    # Returns an empty array. 
    188295    def ancestors 
    189296      [] 
    …… 
    198305    end 
    199306     
     307    # Returns "section". 
    200308    def type 
    201309      "section" 
    …… 
    211319      ebnf.elements.map{|e| e.elements.last } 
    212320    end 
    213          
    214     %w(klass_name full_name name methodized?).each do |name| 
    215       src = <<-END_SRC 
    216         def #{name} 
    217           ebnf_expressions.first.#{name} 
    218         end 
    219       END_SRC 
    220       class_eval src, __FILE__, __LINE__ 
     321 
     322    def klass_name 
     323      ebnf_expressions.first.klass_name 
     324    end 
     325 
     326    def full_name 
     327      ebnf_expressions.first.full_name 
     328    end 
     329 
     330    def name 
     331      ebnf_expressions.first.name 
     332    end 
     333 
     334    def methodized? 
     335      ebnf_expressions.first.methodized? 
    221336    end 
    222337     
    …… 
    335450    end 
    336451     
    337     %w(klass_properties klass_methods instance_properties instance_methods constants).each do |name| 
    338       src = <<-END_SRC 
    339         def #{name} 
    340           root.#{name}.select{|e| e.namespace === self}.sort_by {|e| e.name } 
    341         end 
    342       END_SRC 
    343       class_eval src, __FILE__, __LINE__ 
     452    # Returns a sorted array of KlassProperty 
     453    def klass_properties 
     454      root.klass_properties.select{ |e| e.namespace === self }.sort_by { |e| e.name } 
     455    end 
     456 
     457    # Returns a sorted array of KlassMethod 
     458    def klass_methods 
     459      root.klass_methods.select{ |e| e.namespace === self }.sort_by { |e| e.name } 
     460    end 
     461 
     462    # Returns a sorted array of InstanceProperty 
     463    def instance_properties 
     464      root.instance_properties.select{ |e| e.namespace === self }.sort_by { |e| e.name } 
     465    end 
     466 
     467    # Returns a sorted array of InstanceMethod 
     468    def instance_methods 
     469      root.instance_methods.select{ |e| e.namespace === self }.sort_by { |e| e.name } 
     470    end 
     471 
     472    # Returns a sorted array of Constant 
     473    def constants 
     474      root.constants.select{ |e| e.namespace === self }.sort_by { |e| e.name } 
    344475    end 
    345476     
    346477    def all_methods 
    347       klass_methods.concat(instance_methods).sort_by {|e| e.name } 
     478      klass_methods.concat(instance_methods).sort_by { |e| e.name } 
    348479    end 
    349480     
    350481    def children 
    351       root.descendants.select{|e| e.namespace === self }.sort_by {|e| e.name } 
     482      root.descendants.select{|e| e.namespace === self }.sort_by { |e| e.name } 
    352483    end 
    353484     
    354485    def related_utilities 
    355       root.utilities.select{|e| e.related_to === self}.sort_by {|e| e.name } 
     486      root.utilities.select{|e| e.related_to === self}.sort_by { |e| e.name } 
    356487    end 
    357488