From 1457e6e962408172748083d8b6d39ffa66c19276 Mon Sep 17 00:00:00 2001
From: Valentin Niess <niess@in2p3.fr>
Date: Fri, 18 Mar 2016 22:41:50 +0100
Subject: [PATCH 1/6] Force string encoding to UTF-8.

This prevents a crash when symbols, e.g. &alpha; are encoded using .to_json.
---
 lib/docurium.rb | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/lib/docurium.rb b/lib/docurium.rb
index c2c5bbb8d..15c14741a 100644
--- a/lib/docurium.rb
+++ b/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'
 

From 773fdd377dc0aea5e1168b1d25faadbd2c0ee274 Mon Sep 17 00:00:00 2001
From: Valentin Niess <niess@in2p3.fr>
Date: Sat, 19 Mar 2016 00:10:05 +0100
Subject: [PATCH 2/6] Added callbacks to the struct usage info.

Callbacks as well as functions are now shown in the stats of a structure usage.
---
 lib/docurium.rb     | 7 +++++--
 site/index.html     | 4 ++--
 site/js/docurium.js | 5 ++++-
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/lib/docurium.rb b/lib/docurium.rb
index 15c14741a..4992c5566 100644
--- a/lib/docurium.rb
+++ b/lib/docurium.rb
@@ -378,9 +378,12 @@ 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 => []}
diff --git a/site/index.html b/site/index.html
index 49a5b093a..2bc455afa 100644
--- a/site/index.html
+++ b/site/index.html
@@ -191,7 +191,7 @@ <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>
       <% }) %> <!-- loop over each 'return' -->
@@ -200,7 +200,7 @@ <h3>Returns</h3>
       <% } %> <!-- 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>
       <% }) %> <!-- loop over each 'need' -->
diff --git a/site/js/docurium.js b/site/js/docurium.js
index ff0bd3c8d..903205d2b 100644
--- a/site/js/docurium.js
+++ b/site/js/docurium.js
@@ -606,7 +606,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) {

From 1810453499a87262faa07b153d33dec094edd67b Mon Sep 17 00:00:00 2001
From: Valentin Niess <niess@in2p3.fr>
Date: Sun, 20 Mar 2016 00:23:34 +0100
Subject: [PATCH 3/6] Added a callback entry to the sidebar.

Callbacks appear in the `Types` menu. In addition if a type is missing, e.g. opaques structures, the corresponding sub-menu doesnt appear anymore.
---
 site/js/docurium.js | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/site/js/docurium.js b/site/js/docurium.js
index 903205d2b..b0ac50940 100644
--- a/site/js/docurium.js
+++ b/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
@@ -581,7 +599,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')

From 04a516bf64b26b93fa8b75aec736254ed68a221e Mon Sep 17 00:00:00 2001
From: Valentin Niess <niess@in2p3.fr>
Date: Sun, 20 Mar 2016 22:27:32 +0100
Subject: [PATCH 4/6] Some cosmetic tunnings.

Also link doesn't show the current function anymore.
Added commas separator and dot for the list of links to Argument in/returned by, in structures.
---
 site/index.html     | 14 ++++++++------
 site/js/docurium.js |  2 +-
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/site/index.html b/site/index.html
index 2bc455afa..4df478045 100644
--- a/site/index.html
+++ b/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>
@@ -193,19 +195,19 @@ <h2 class="funcGroup"><%= group.name %></h2>
       <% if (returns.length > 0) { %>
       <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>
       <% _.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">
diff --git a/site/js/docurium.js b/site/js/docurium.js
index b0ac50940..da90213a5 100644
--- a/site/js/docurium.js
+++ b/site/js/docurium.js
@@ -241,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

From 4a4d1e9edf2e0f1d70c6cc0165210b38d7749850 Mon Sep 17 00:00:00 2001
From: Valentin Niess <niess@in2p3.fr>
Date: Sun, 20 Mar 2016 23:57:15 +0100
Subject: [PATCH 5/6] Patching a regexp bug.

Exact matching of `returned by/argument in` is now allowed.
---
 lib/docurium.rb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/docurium.rb b/lib/docurium.rb
index 4992c5566..16105896b 100644
--- a/lib/docurium.rb
+++ b/lib/docurium.rb
@@ -387,11 +387,11 @@ def find_type_usage!(data)
       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

From 1bfdc4d7d55342bd76e02c0022a21f13c8e76cc1 Mon Sep 17 00:00:00 2001
From: Valentin Niess <niess@in2p3.fr>
Date: Fri, 25 Mar 2016 00:12:48 +0100
Subject: [PATCH 6/6] Corrected a bug resulting in function's group not being
 displayed.

---
 site/js/docurium.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/site/js/docurium.js b/site/js/docurium.js
index da90213a5..a7cf49e10 100644
--- a/site/js/docurium.js
+++ b/site/js/docurium.js
@@ -409,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]