Merge branch 'callbacks'

Author: carlosmn

lib/docurium.rb

@@ -27,7 +27,7 @@ def initialize(config_file, repo = nil)
   end
 
   def init_data(version = 'HEAD')
-    data = {:files => [], :functions => {}, :globals => {}, :types => {}, :prefix => ''}
+    data = {:files => [], :functions => {}, :callbacks => {}, :globals => {}, :types => {}, :prefix => ''}
     data[:prefix] = option_version(version, 'input', '')
     data
   end
@@ -389,17 +389,17 @@ def update_globals!(data, recs)
 
       # process this type of record
       case r[:type]
-      when :function
-        data[:functions][r[:name]] ||= {}
+      when :function, :callback
+          t = r[:type] == :function ? :functions : :callbacks
+        data[t][r[:name]] ||= {}
         wanted[:functions].each do |k|
           next unless r.has_key? k
-          conents = nil
           if k == :description || k == :comments
             contents = md.render r[k]
           else
             contents = r[k]
           end
-          data[:functions][r[:name]][k] = contents
+          data[t][r[:name]][k] = contents
         end
         file_map[r[:file]][:functions] << r[:name]
 

lib/docurium/docparser.rb

@@ -111,11 +111,15 @@ def extract_typedef(cursor)
         #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
+        rec.merge! extract_function(cursor)
+        rec[:type] = :callback
+        # this is wasteful, but we don't get the array from outside
+        cmt = extract_function_comment(cursor.comment)
+        ret = {
+               :type => extract_callback_result(rec[:underlying_type]),
+               :comment => cmt[:return]
+              }
+        rec[:return] = ret
       else
         raise "No idea how to handle #{child.kind}"
       end
@@ -125,21 +129,14 @@ def extract_typedef(cursor)
       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
+    def extract_callback_result(type)
+      type[0..(type.index('(') - 1)].strip
     end
 
-    def extract_function(cursor)
-      comment = cursor.comment
-
-      #puts "looking at function #{cursor.spelling}, #{cursor.display_name}"
-      cmt = extract_function_comment(comment)
-
+    def extract_function_args(cursor, cmt)
       # We only want to look at parm_decl to avoid looking at a return
       # struct as a parameter
-      args = children(cursor)
+      children(cursor)
         .select {|c| c.kind == :cursor_parm_decl }
         .map do |arg|
         {
@@ -148,6 +145,20 @@ def extract_function(cursor)
           :comment => cmt[:args][arg.display_name],
         }
       end
+    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)
+      args = extract_function_args(cursor, cmt)
       #args = args.reject { |arg| arg[:comment].nil? }
 
       ret = {

site/index.html

@@ -138,6 +138,7 @@ <h3>signature</h3>
        <code class="params"><%= sig %></code>
      </div>
      <!-- function history -->
+     <% if (sigs) { %>
      <div class="signatures">
        <h3>versions</h3>
        <ul>
@@ -146,6 +147,7 @@ <h3>versions</h3>
 	 <% }) %>
        </ul>
      </div>
+     <% } %> <!-- if we have version history -->
      <div class="fileLink">Defined in: <a href="<%= fileLink %>"> <%= data.file %></a></div>
      <% if (data.examples) { %>
      <div class="funcEx">Used in examples:
@@ -161,6 +163,7 @@ <h3>versions</h3>
      </ul>
      </div>
      <% } %> <!-- if we have examples -->
+     <% if (alsoLinks) { %>
      <div class="also">
        Also in <a href="<%= alsoGroup %>"><%= groupName %></a> group: <br/>
        <% _.each(_.initial(alsoLinks), function(link) { %>
@@ -169,6 +172,7 @@ <h3>versions</h3>
        <% var link = _.last(alsoLinks) %>
        <a href="<%= link.url %>"><%= link.name %></a>
      </div>
+     <% } %> <!-- if we have "also" links -->
     </script>
 
     <!-- main page, list of groups and their functions -->

site/js/docurium.js

@@ -213,42 +213,54 @@ $(function() {
       var fname = this.get('fname')
       var docurium = this.get('docurium')
 
+      var isCallback = gname === 'callback'
       var group = docurium.getGroup(gname)
 
       var fdata = docurium.get('data')['functions']
-      var functions = group[1]
+
+      var ldata = fdata
+      if (isCallback) {
+	var cdata = docurium.get('data')['callbacks']
+	ldata = cdata
+      } else {
+	var functions = group[1]
+      }
 
       // Function Arguments
-      var args = _.map(fdata[fname]['args'], function(arg) {
+      var args = _.map(ldata[fname]['args'], function(arg) {
 	return {link: this.hotLink(arg.type), name: arg.name, comment: arg.comment}
       }, docurium)
 
-      var data = fdata[fname]
+      var data = ldata[fname]
       // function return value
       var ret = data['return']
       var returns = {link: docurium.hotLink(ret.type), comment: ret.comment}
       // function signature
       var sig = docurium.hotLink(ret.type) + ' ' + fname + '(' + data['argline'] + ');'
       // version history
-      var sigHist = docurium.get('signatures')[fname]
-      var version = docurium.get('version')
-      var sigs = _.map(sigHist.exists, function(ver) {
-	var klass = []
-	if (sigHist.changes[ver])
-	  klass.push('changed')
-	if (ver == version)
-	  klass.push('current')
-
-	return {url: '#' + functionLink(gname, fname, ver), name: ver, klass: klass.join(' ')}
-      })
+      if (!isCallback) {
+	var sigHist = docurium.get('signatures')[fname]
+	var version = docurium.get('version')
+	var sigs = _.map(sigHist.exists, function(ver) {
+	  var klass = []
+	  if (sigHist.changes[ver])
+	    klass.push('changed')
+	  if (ver == version)
+	    klass.push('current')
+
+	  return {url: '#' + functionLink(gname, fname, ver), name: ver, klass: klass.join(' ')}
+	})
+      }
       // GitHub link
       var fileLink = docurium.github_file(data.file, data.line, data.lineto)
       // link to the group
-      var version = docurium.get('version')
-      var alsoGroup = '#' + groupLink(group[0], version)
-      var alsoLinks = _.map(functions, function(f) {
-	return {url: '#' + functionLink(gname, f, version), name: f}
-      })
+      if (!isCallback) {
+	var version = docurium.get('version')
+	var alsoGroup = '#' + groupLink(group[0], version)
+	var alsoLinks = _.map(functions, function(f) {
+	  return {url: '#' + functionLink(gname, f, version), name: f}
+	})
+      }
 
       this.set('data', {name: fname, data: data, args: args, returns: returns, sig: sig,
 			sigs: sigs, fileLink: fileLink, groupName: gname,
@@ -381,6 +393,7 @@ $(function() {
       var group = o.group
       var gname = group[0]
       var fdata = o.functions
+      var cdata = o.callbacks
       var version = o.version
 
       this.functions = _.map(group[1], function(name) {
@@ -471,6 +484,16 @@ $(function() {
         }
       })
 
+      // look for callbacks
+      _.each(data.callbacks, function(f, name) {
+	if (name.search(value) > -1) {
+	  var gl = functionLink('callback', name, version)
+	  var url = '#' + gl
+	  searchResults.push({url: url, name: name, match: 'callback', navigate: gl})
+	  return
+	}
+      })
+
       this.reset(searchResults)
     },
   })
@@ -556,14 +579,23 @@ $(function() {
     hotLink: function(text) {
       types = this.get('data')['types']
       var version = this.get('version')
+
       for(var i=0; i<types.length; i++) {
         type = types[i]
         typeName = type[0]
         typeData = type[1]
-        re = new RegExp(typeName + ' ', 'gi');
+        re = new RegExp(typeName + '\\s', 'gi');
         var link = $('<a>').attr('href', '#' + typeLink(typeName, version)).append(typeName)[0]
         text = text.replace(re, link.outerHTML + ' ')
       }
+
+      var callbacks = this.get('data')['callbacks']
+      _.each(callbacks, function(cb, typeName) {
+        re = new RegExp(typeName + '$', 'gi');
+        var link = $('<a>').attr('href', '#' + functionLink('callback', typeName, version)).append(typeName)[0]
+        text = text.replace(re, link.outerHTML + ' ')
+      });
+
       return text
     },
 
@@ -624,8 +656,9 @@ $(function() {
       this.doc.setVersion(version)
       var group = this.doc.getGroup(gname)
       var fdata = this.doc.get('data')['functions']
+      var cdata = this.doc.get('data')['callbacks']
       var version = this.doc.get('version')
-      var view = new GroupView({group: group, functions: fdata, version: version})
+      var view = new GroupView({group: group, functions: fdata, callbacks: cdata, version: version})
       this.mainView.setActive(view)
     },
 

test/fixtures/git2/callback.h

@@ -0,0 +1,16 @@
+/*
+ * This file is to create a function which takes a callback in order
+ * to test that we detect it correctly and will write it out.
+ */
+
+#include "common.h"
+
+/**
+ * Worker which does soemthing to its pointer
+ */
+typedef int (*git_callback_do_work)(int *foo);
+
+/**
+ * Schedule some work to happen for a particular function
+ */
+GIT_EXTERN(int) git_work_schedule(git_callback_do_work worker);

test/parser_test.rb

@@ -406,4 +406,41 @@ def test_type_reference
 
   end
 
+  def test_callaback
+    name = 'typeref.h'
+    contents = <<EOF
+/**
+* This is a callback type
+*
+* @return whether to reschedule
+*/
+typedef int (*some_callback)(int *foo);
+EOF
+
+    actual = parse(name, contents)
+    expected = [{
+                  :file => "typeref.h",
+                  :line => 6,
+                  :lineto => 6,
+                  :tdef => :typedef,
+                  :name => "some_callback",
+                  :underlying_type => "int (*)(int *)",
+                  :type => :callback,
+                  :body => ' some_callback(int *foo);',
+                  :description => ' This is a callback type',
+                  :comments => ' ',
+                  :sig => "int *",
+                  :args => [{:name => "foo",
+                             :type => "int *",
+                             :comment => nil,
+                            }],
+                  :return => {:type => 'int',
+                              :comment => " whether to reschedule"},
+                  :decl => ' some_callback(int *foo)',
+                  :argline => 'int *foo',
+                }]
+
+    assert_equal actual, expected
+  end
+
 end

test/repo_test.rb

@@ -39,8 +39,8 @@ def teardown
 
   def test_can_parse_headers
     keys = @data.keys.map { |k| k.to_s }.sort
-    assert_equal ['files', 'functions', 'globals', 'groups', 'prefix', 'types'], keys
-    assert_equal 153, @data[:functions].size
+    assert_equal ['callbacks', 'files', 'functions', 'globals', 'groups', 'prefix', 'types'], keys
+    assert_equal 154, @data[:functions].size
   end
 
   def test_can_extract_enum_from_define
@@ -114,7 +114,7 @@ def test_can_get_the_full_description_from_multi_liners
   end
 
   def test_can_group_functions
-    assert_equal 14, @data[:groups].size
+    assert_equal 15, @data[:groups].size
     group, funcs = @data[:groups].first
     assert_equal 'blob', group
     assert_equal 6, funcs.size
@@ -127,4 +127,10 @@ def test_can_store_mutliple_enum_doc_sections
     assert_equal 2, idxentry[1][:sections].size
   end
 
+  def test_can_parse_callback
+    cb = @data[:callbacks]['git_callback_do_work']
+    # we can mostly assume that the rest works as it's the same as for the functions
+    assert_equal 'int', cb[:return][:type]
+  end
+
 end