Merge pull request #23 from niess/master

Some tweaks and more love for callbacks

Author: carlosmn

lib/docurium.rb

@@ -167,6 +167,7 @@ def generate_docs
 
       # There's still some work we need to do serially
       tally_sigs!(version, data)
+      force_utf8(data)
       sha = @repo.write(data.to_json, :blob)
 
       print "Generating documentation [#{i}/#{nversions}]\r"
@@ -225,6 +226,21 @@ def generate_docs
     puts "\tupdated #{br}"
   end
 
+  def force_utf8(data)
+    # Walk the data to force strings encoding to UTF-8.
+    if data.instance_of? Hash
+      data.each do |key, value|
+        if [:comment, :comments, :description].include?(key)
+          data[key] = value.force_encoding('UTF-8') unless value.nil?
+        else
+          force_utf8(value)
+        end
+      end
+    elsif data.respond_to?(:each)
+      data.each { |x| force_utf8(x) }
+    end
+  end
+
   def show_warnings(data)
     out '* checking your api'
 
@@ -362,17 +378,20 @@ def group_functions!(data)
   end
 
   def find_type_usage!(data)
-    # go through all the functions and see where types are used and returned
+    # go through all the functions and callbacks and see where other types are used and returned
     # store them in the types data
-    data[:functions].each do |func, fdata|
+    h = {}
+    h.merge!(data[:functions])
+    h.merge!(data[:callbacks])
+    h.each do |func, fdata|
       data[:types].each_with_index do |tdata, i|
         type, typeData = tdata
         data[:types][i][1][:used] ||= {:returns => [], :needs => []}
-        if fdata[:return][:type].index(/#{type}[ ;\)\*]/)
+        if fdata[:return][:type].index(/#{type}[ ;\)\*]?/)
           data[:types][i][1][:used][:returns] << func
           data[:types][i][1][:used][:returns].sort!
         end
-        if fdata[:argline].index(/#{type}[ ;\)\*]/)
+        if fdata[:argline].index(/#{type}[ ;\)\*]?/)
           data[:types][i][1][:used][:needs] << func
           data[:types][i][1][:used][:needs].sort!
         end

site/index.html

@@ -92,6 +92,7 @@ <h3><a href="#">Files</a></h3>
 	 <% }) %>
        </ul>
      </li>
+     <% if (examples.length > 0) { %>
      <li>
        <h3><a href="#">Examples</a></h3>
        <ul>
@@ -102,6 +103,7 @@ <h3><a href="#">Examples</a></h3>
 	 <% }) %>
        </ul>
      </li>
+    <% } %> <!-- if we have examples -->
     </script>
 
     <!-- Listing of the details of a single function -->
@@ -162,14 +164,14 @@ <h3>versions</h3>
      </ul>
      </div>
      <% } %> <!-- if we have examples -->
-     <% if (alsoLinks) { %>
+     <% if (alsoLinks && (alsoLinks.length > 0)) { %>
      <div class="also">
        Also in <a href="<%= alsoGroup %>"><%= groupName %></a> group: <br/>
        <% _.each(_.initial(alsoLinks), function(link) { %>
        <a href="<%= link.url %>"><%= link.name %></a>, 
        <% }) %>
        <% var link = _.last(alsoLinks) %>
-       <a href="<%= link.url %>"><%= link.name %></a>
+       <a href="<%= link.url %>"><%= link.name %></a>.
      </div>
      <% } %> <!-- if we have "also" links -->
     </script>
@@ -191,21 +193,21 @@ <h2 class="funcGroup"><%= group.name %></h2>
 
     <script type="text/template" id="uses-template">
       <% if (returns.length > 0) { %>
-      <h3>Returns</h3>
+      <h3>Returned by</h3>
       <% _.each(_.initial(returns), function(fun) { %>
-      <a href="<%= fun.url %>"><%= fun.name %></a>
+      <a href="<%= fun.url %>"><%= fun.name %></a>,
       <% }) %> <!-- loop over each 'return' -->
       <% var fun = _.last(returns) %>
-      <a href="<%= fun.url %>"><%= fun.name %></a>
+      <a href="<%= fun.url %>"><%= fun.name %></a>.
       <% } %> <!-- if we have 'returns' -->
 
       <% if (needs.length > 0) { %>
-      <h3>Argument In</h3>
+      <h3>Argument in</h3>
       <% _.each(_.initial(needs), function(fun) { %>
-      <a href="<%= fun.url %>"><%= fun.name %></a>
+      <a href="<%= fun.url %>"><%= fun.name %></a>,
       <% }) %> <!-- loop over each 'need' -->
       <% var fun = _.last(needs) %>
-      <a href="<%= fun.url %>"><%= fun.name %></a>
+      <a href="<%= fun.url %>"><%= fun.name %></a>.
       <% } %> <!-- if we have 'needs' -->
 
       <div class="fileLink">

site/js/docurium.js

@@ -17,6 +17,12 @@ $(function() {
 	return {name: name, link: link, num: group[1].length}
       })
 
+      // Callbacks
+      var callbacks = _.map(_.keys(data['callbacks']), function(name) {
+	var link = functionLink('callback', name, version)
+	return {name: name, link: link}
+      })
+
       // Types
       var getName = function(type) {
 	var name = type[0];
@@ -50,8 +56,8 @@ $(function() {
 	})
       }
 
-      this.set('data', {funs: funs, enums: enums, structs: structs, opaques: opaques,
-			files: files, examples: examples})
+      this.set('data', {funs: funs, callbacks: callbacks, enums: enums, structs: structs,
+	                opaques: opaques, files: files, examples: examples})
     },
   })
 
@@ -78,12 +84,24 @@ $(function() {
     render: function() {
       var data = this.model.get('data')
 
-      var enumList = this.typeTemplate({title: 'Enums', elements: data.enums})
-      var structList = this.typeTemplate({title: 'Structs', elements: data.structs})
-      var opaquesList = this.typeTemplate({title: 'Opaque Structs', elements: data.opaques})
       var menu = $(this.template({funs: data.funs, files: data.files, examples: data.examples}))
 
-      $('#types-list', menu).append(enumList, structList, opaquesList)
+      if (data.enums.length) {
+          var enumList = this.typeTemplate({title: 'Enums', elements: data.enums})
+          $('#types-list', menu).append(enumList)
+      }
+      if (data.structs.length) {
+          var structList = this.typeTemplate({title: 'Structs', elements: data.structs})
+          $('#types-list', menu).append(structList)
+      }
+      if (data.opaques.length) {
+          var opaquesList = this.typeTemplate({title: 'Opaque Structs', elements: data.opaques})
+          $('#types-list', menu).append(opaquesList)
+      }
+      if (data.callbacks.length) {
+          var callbacksList = this.typeTemplate({title: 'Callbacks', elements: data.callbacks})
+          $('#types-list', menu).append(callbacksList)
+      }
 
       this.$el.html(menu)
       return this
@@ -223,7 +241,7 @@ $(function() {
 	var cdata = docurium.get('data')['callbacks']
 	ldata = cdata
       } else {
-	var functions = group[1]
+	var functions = _.filter(group[1], function(f){ return f != fname})
       }
 
       // Function Arguments
@@ -391,6 +409,7 @@ $(function() {
       var cdata = o.callbacks
       var version = o.version
 
+      this.gname = gname.charAt(0).toUpperCase() + gname.substring(1).toLowerCase()
       this.functions = _.map(group[1], function(name) {
 	var url = '#' + functionLink(gname, name, version)
 	var d = fdata[name]
@@ -581,7 +600,7 @@ $(function() {
       })
     },
 
-    // look for structs and link them 
+    // look for structs and link them
     hotLink: function(text) {
       types = this.get('data')['types']
       var version = this.get('version')
@@ -606,7 +625,10 @@ $(function() {
     },
 
     groupOf: function (func) {
-      return this.get('data')['functions'][func]['group']
+      if(func in this.get('data')['functions']) {
+        return this.get('data')['functions'][func]['group']
+      }
+      return 'callback'
     },
 
     github_file: function(file, line, lineto) {