docurium 0.3.2 → 0.4.0

data/lib/docurium/docparser.rb

@@ -0,0 +1,292 @@
+require 'ffi/clang'
+include FFI::Clang
+
+class Docurium
+  class DocParser
+    # Entry point for this parser
+    # Parse `filename` out of the hash `files`
+    def parse_file(orig_filename, files)
+
+      # unfortunately Clang wants unsaved files to exist on disk, so
+      # we need to create at least empty files for each unsaved file
+      # we're given.
+
+      tmpdir = Dir.mktmpdir()
+
+      unsaved = files.map do |name, contents|
+        full_path = File.join(tmpdir, name)
+        dirname = File.dirname(full_path)
+        Dir.mkdir(dirname) unless Dir.exists? dirname
+        File.new(full_path, File::CREAT).close()
+
+        UnsavedFile.new(full_path, contents)
+      end
+
+      # Override the path we want to filter by
+      filename = File.join(tmpdir, orig_filename)
+      tu = Index.new.parse_translation_unit(filename, [], unsaved, {:detailed_preprocessing_record => 1})
+
+      FileUtils.remove_entry(tmpdir)
+
+      cursor = tu.cursor
+
+      recs = []
+
+      cursor.visit_children do |cursor, parent|
+        #puts "visiting #{cursor.kind} - #{cursor.spelling}"
+        location = cursor.location
+        next :continue if location.file == nil
+        next :continue unless location.file == filename
+
+        #puts "for file #{location.file} #{cursor.kind} #{cursor.spelling} #{cursor.comment.kind} #{location.line}"
+        #cursor.visit_children do |c|
+        #  puts "  child #{c.kind}, #{c.spelling}, #{c.comment.kind}"
+        #  :continue
+        #end
+
+        next :continue if cursor.comment.kind == :comment_null
+        next :continue if cursor.spelling == ""
+
+        extent = cursor.extent
+        rec = {
+          :file => orig_filename,
+          :line => extent.start.line,
+          :lineto => extent.end.line,
+          :tdef => nil,
+        }
+
+        case cursor.kind
+        when :cursor_function
+          #puts "have function"
+          rec.merge! extract_function(cursor)
+        when :cursor_enum_decl
+          rec.merge! extract_enum(cursor)
+        when :cursor_struct
+          #puts "raw struct"
+          rec.merge! extract_struct(cursor)
+        when :cursor_typedef_decl
+          rec.merge! extract_typedef(cursor)
+        else
+          raise "No idea how to deal with #{cursor.kind}"
+        end
+
+        recs << rec
+        :continue
+      end
+
+      recs
+    end
+
+    def extract_typedef(cursor)
+      child = nil
+      cursor.visit_children { |c| child = c; :break }
+      rec = {
+        :name => cursor.spelling,
+        :underlying_type => cursor.underlying_type.spelling,
+        :tdef => :typedef,
+      }
+
+      if not child
+        return rec
+      end
+
+      #puts "have typedef #{child.kind}, #{cursor.extent.start.line}"
+      case child.kind
+      when :cursor_type_ref
+        #puts "pure typedef, #{cursor.spelling}"
+        if child.type.kind == :type_record
+          rec[:type] = :struct
+          subject, desc = extract_subject_desc(cursor.comment)
+          rec[:decl] = cursor.spelling
+          rec[:description] = subject
+          rec[:comments] = desc
+        else
+          raise "typede of unhandled #{child.type.kind}"
+        end
+      when :cursor_enum_decl
+        rec.merge! extract_enum(child)
+      when :cursor_struct
+        #puts "typed struct, #{cursor.spelling}"
+        rec.merge! extract_struct(child)
+      when :cursor_parm_decl
+        #puts "have parm #{cursor.spelling}, #{cursor.display_name}"
+        subject, desc = extract_subject_desc(cursor.comment)
+        rec[:decl] = cursor.spelling
+        rec[:description] = subject
+        rec[:comments] = desc
+      when :cursor_type_ref
+        rec[:decl] = cursor.spelling
+      else
+        raise "No idea how to handle #{child.kind}"
+      end
+      # let's make sure we override the empty name the extract
+      # functions stored
+      rec[:name] = cursor.spelling
+      rec
+    end
+
+    def extract_subject_desc(comment)
+      subject = comment.child.text
+      desc = (comment.find_all { |cmt| cmt.kind == :comment_paragraph }).drop(1).map(&:text).join("\n\n")
+      return subject, desc
+    end
+
+    def extract_function(cursor)
+      comment = cursor.comment
+
+      #puts "looking at function #{cursor.spelling}, #{cursor.display_name}"
+      cmt = extract_function_comment(comment)
+
+      # We only want to look at parm_decl to avoid looking at a return
+      # struct as a parameter
+      args = children(cursor)
+        .select {|c| c.kind == :cursor_parm_decl }
+        .map do |arg|
+        {
+          :name => arg.display_name,
+          :type => arg.type.spelling,
+          :comment => cmt[:args][arg.display_name],
+        }
+      end
+      #args = args.reject { |arg| arg[:comment].nil? }
+
+      ret = {
+        :type => cursor.result_type.spelling,
+        :comment => cmt[:return]
+      }
+
+      # generate function signature
+      sig = args.map { |a| a[:type].to_s }.join('::')
+
+      argline = args.map { |a|
+        # pointers don't have a separation between '*' and the name
+        if a[:type].end_with? "*"
+          "#{a[:type]}#{a[:name]}"
+        else
+          "#{a[:type]} #{a[:name]}"
+        end
+      }.join(', ')
+
+      decl = "#{ret[:type]} #{cursor.spelling}(#{argline})"
+      body = "#{decl};"
+
+      #puts cursor.display_name
+      # Return the format that docurium expects
+      {
+        :type => :function,
+        :name => cursor.spelling,
+        :body => body,
+        :description => cmt[:description],
+        :comments => cmt[:comments],
+        :sig => sig,
+        :args => args,
+        :return => ret,
+        :decl => decl,
+        :argline => argline
+      }
+    end
+
+    def extract_function_comment(comment)
+      subject, desc = extract_subject_desc(comment)
+
+      args = {}
+      (comment.find_all { |cmt| cmt.kind == :comment_param_command }).each do |param|
+        args[param.name] = param.comment.strip
+      end
+
+      ret = nil
+      comment.each do |block|
+        next unless block.kind == :comment_block_command
+        next unless block.name == "return"
+
+        ret = block.paragraph.text
+
+        break
+      end
+
+      {
+        :description => subject,
+        :comments => desc,
+        :args => args,
+        :return => ret,
+      }
+    end
+
+    def extract_fields(cursor)
+      fields = []
+      cursor.visit_children do |cchild, cparent|
+        field = {
+          :type => cchild.type.spelling,
+          :name => cchild.spelling,
+          :comments => cchild.comment.find_all {|c| c.kind == :comment_paragraph }.map(&:text).join("\n\n")
+        }
+
+        if cursor.kind == :cursor_enum_decl
+          field.merge!({:value => cchild.enum_value})
+        end
+
+        fields << field
+        :continue
+      end
+
+        fields
+    end
+
+    def extract_enum(cursor)
+      subject, desc = extract_subject_desc(cursor.comment)
+
+      decl = []
+      cursor.visit_children do |cchild, cparent|
+        decl << cchild.spelling
+        :continue
+      end
+
+      block = decl.join("\n")
+      #return the docurium object
+      {
+        :type => :enum,
+        :name => cursor.spelling,
+        :description => subject,
+        :comments => desc,
+        :fields => extract_fields(cursor),
+        :block => block,
+        :decl => decl,
+      }
+    end
+
+    def extract_struct(cursor)
+      subject, desc = extract_subject_desc(cursor.comment)
+
+      values = []
+      cursor.visit_children do |cchild, cparent|
+        values << "#{cchild.type.spelling} #{cchild.spelling}"
+        :continue
+      end
+
+      #puts "struct value #{values}"
+
+      rec = {
+        :type => :struct,
+        :name => cursor.spelling,
+        :description => subject,
+        :comments => desc,
+        :fields => extract_fields(cursor),
+        :decl => values,
+      }
+
+      rec[:block] = values.join("\n") unless values.empty?
+      rec
+    end
+
+    def children(cursor)
+      list = []
+      cursor.visit_children do |ccursor, cparent|
+        list << ccursor
+        :continue
+      end
+
+      list
+    end
+
+  end
+end

data/lib/docurium/version.rb

@@ -1,3 +1,3 @@
 class Docurium
-  Version = VERSION = '0.3.2'
+  Version = VERSION = '0.4.0'
 end

data/lib/libdetect.rb

@@ -0,0 +1,23 @@
+require 'rbconfig'
+require 'mkmf'
+
+# This is pretty terrible, but we need to have the environment set up
+# before we require the ffi-clang module.
+
+module LibDetect
+
+  DARWIN_LIBCLANG = '/Library/Developer/CommandLineTools/usr/lib/libclang.dylib'
+
+  host_os = RbConfig::CONFIG['host_os']
+  case host_os
+  when /darwin/
+    File.exist? DARWIN_LIBCLANG
+    ENV['LIBCLANG'] = DARWIN_LIBCLANG
+  when /linux/
+    prog = 'llvm-config-3.4'
+    if find_executable(prog)
+      ENV['LLVM_CONFIG'] = prog
+    end
+  end
+
+end

data/site/css/style.css

@@ -254,3 +254,7 @@ p.functionList a.introd {
 .changelog li.deletes {
   color: #933;
 }
+
+.type-comment {
+  padding-left: 3em;
+}

data/site/index.html

@@ -186,16 +186,7 @@
       <% }) %> <!-- loop through the groups -->
     </script>
 
-    <!-- listing for a particular type -->
-    <script type="text/template" id="type-template">
-      <h1 class="funcTitle"><%= tname %><small><%= data.type %></small></h1>
-      <p><%= data.value %></p>
-      <% if (data.comments) { %>
-      <div><%= data.comments %></div>
-      <% } %>
-      <% if (data.block) { %>
-      <pre><%= data.block %></pre>
-      <% } %>
+    <script type="text/template" id="uses-template">
       <% if (returns.length > 0) { %>
       <h3>Returns</h3>
       <% _.each(_.initial(returns), function(fun) { %>
@@ -220,6 +211,61 @@
       </div>
     </script>
 
+    <!-- listing for an enum -->
+    <script type="text/template" id="enum-template">
+      <h1 class="funcTitle"><%= type.tname %><small><%= type.type %></small></h1>
+      <p><%= type.value %></p>
+
+      <% if (type.data.description) { %>
+      <p><%= type.data.description %></p>
+      <% } %>
+      <% if (type.data.comments) { %>
+      <p><%= type.data.comments %></p>
+      <% } %>
+
+      <table>
+	<% _.each(type.data.fields, function(field) { %>
+	<tr>
+	  <td><code><%= field.name %></code></td>
+	<tr>
+	  <% if (field.comments) { %>
+	  <tr>
+	    <td class="type-comment"><%= field.comments %></td>
+	  </tr>
+	  <% } %>
+	<% }) %>
+      </table>
+      <%= uses %>
+    </script>
+    <!-- listing for a struct -->
+    <script type="text/template" id="struct-template">
+      <h1 class="funcTitle"><%= type.tname %><small><%= type.type %></small></h1>
+      <p><%= type.value %></p>
+
+      <% if (type.data.description) { %>
+      <p><%= type.data.description %></p>
+      <% } %>
+      <% if (type.data.comments) { %>
+      <p><%= type.data.comments %></p>
+      <% } %>
+
+      <table>
+	<% _.each(type.data.fields, function(field) { %>
+	<tr>
+	  <td><code><%= field.type %></code></td>
+	  <td><code><%= field.name %></code></td>
+	<tr>
+	  <% if (field.comments) { %>
+	  <tr>
+	    <td colspan="2" class="type-comment"><%= field.comments %></td>
+	  </tr>
+	  <% } %>
+	<% }) %>
+      </table>
+
+      <%= uses %>
+    </script>
+
     <script type="text/template" id="group-template">
       <h1><%= gname %> functions</h1>
       <!-- table with all the functions -->

data/site/js/docurium.js

@@ -337,15 +337,38 @@ $(function() {
       var needs = _.map(data.used.needs, toPair, docurium)
       var fileLink = {name: data.file, url: docurium.github_file(data.file, data.line, data.lineto)}
 
-      this.set('data', {tname: tname, data: data, returns: returns, needs: needs, fileLink: fileLink})
+      // so it doesn't look crap, we build up a block with fields
+      // without a comment
+      var had_comment = false
+      var blocks = []
+      var tmp = []
+      _.each(data.fields, function(f) {
+	if (had_comment) {
+	  blocks.push(tmp)
+	  tmp = []
+	}
+
+	tmp.push(f)
+	had_comment = f.comments
+      })
+      blocks.push(tmp)
+
+      this.set('data', {tname: tname, data: data, blocks: blocks, returns: returns, needs: needs, fileLink: fileLink})
     }
   })
 
   var TypeView = Backbone.View.extend({
-    template: _.template($('#type-template').html()),
+    enumTemplate: _.template($('#enum-template').html()),
+    structTemplate: _.template($('#struct-template').html()),
+    usesTemplate: _.template($('#uses-template').html()),
 
     render: function() {
-      var content = this.template(this.model.get('data'))
+      var type = this.model.get('data')
+      var uses = this.usesTemplate(type)
+
+      var template = type.data.type == 'struct' ? this.structTemplate : this.enumTemplate
+      var content = template({type: type, uses: uses})
+
       this.el = content
       return this
     }
@@ -503,7 +526,7 @@ $(function() {
 
     loadVersions: function() {
       $.getJSON("project.json").then(function(data) {
-        docurium.set({'versions': data.versions, 'github': data.github, 'signatures': data.signatures, 'name': data.name, 'groups': data.groups})
+        docurium.set({'versions': data.versions, 'github': data.github, 'signatures': data.signatures, 'name': data.name})
         docurium.setVersion()
       })
     },
@@ -545,7 +568,7 @@ $(function() {
     },
 
     groupOf: function (func) {
-      return this.get('groups')[func]
+      return this.get('data')['functions'][func]['group']
     },
 
     github_file: function(file, line, lineto) {