Merge pull request #38 from tiennou/fix/struct-style

Restyle structs

Author: carlosmn

lib/docurium.rb

@@ -502,13 +502,24 @@ def update_globals!(data, recs)
 
       when :struct, :fnptr
         data[:types][r[:name]] ||= {}
+        known = data[:types][r[:name]]
         r[:value] ||= r[:name]
-        wanted[:types].each do |k|
-          next unless r.has_key? k
-          if k == :comments
-            data[:types][r[:name]][k] = md.render r[k]
-          else
-            data[:types][r[:name]][k] = r[k]
+        # we don't want to override "opaque" structs with typedefs or
+        # "public" documentation
+        unless r[:tdef].nil? and known[:fields] and known[:comments] and known[:description]
+          wanted[:types].each do |k|
+            next unless r.has_key? k
+            if k == :comments
+              data[:types][r[:name]][k] = md.render r[k]
+            else
+              data[:types][r[:name]][k] = r[k]
+            end
+          end
+        else
+          # We're about to skip that type. Just make sure we preserve the
+          # :fields comment
+          if r[:fields] and known[:fields].empty?
+            data[:types][r[:name]][:fields] = r[:fields]
           end
         end
         if r[:type] == :fnptr

lib/docurium/docparser.rb

@@ -147,7 +147,7 @@ def extract_function_args(cursor, cmt)
 
     def extract_subject_desc(comment)
       subject = comment.child.text
-      paras = comment.find_all { |cmt| cmt.kind == :comment_paragraph }.drop(1).map { |p| p.map(&:text).join() }
+      paras = comment.find_all { |cmt| cmt.kind == :comment_paragraph }.drop(1).map { |p| p.text }
       desc = paras.join("\n\n")
       return subject, desc
     end

site/css/style.css

@@ -117,18 +117,25 @@ table.methods tr td.methodName a {
   font-weight: bold;
 }
 
-table.funcTable tr td {
+table.funcTable tr td,
+table.structTable tr td {
   padding: 5px 10px;
   border-bottom: 1px solid #eee;
 }
-table.funcTable tr td.comment {
-  color: #999;
-}
-table.funcTable tr td.var {
+
+.enumTable .var,
+.funcTable .var,
+.structTable .var {
   font-weight: bold;
   color: #833;
 }
 
+.enumTable .type,
+.funcTable .type,
+.structTable .type {
+  text-align: right;
+}
+
 code.params {
  white-space: pre-wrap;       /* css-3 */
  white-space: -moz-pre-wrap;  /* Mozilla, since 1999 */
@@ -152,7 +159,9 @@ code.params {
 
 .returns { margin-bottom: 15px; }
 
-h1.funcTitle {
+h1.funcTitle,
+h1.enumTitle,
+h1.structTitle {
   font-size: 1.6em;
 }
 h3.funcDesc {
@@ -255,6 +264,3 @@ p.functionList a.introd {
   color: #933;
 }
 
-.type-comment {
-  padding-left: 3em;
-}

site/index.html

@@ -111,8 +111,10 @@ <h3><a href="#">Examples</a></h3>
       <table class="funcTable">
         <% _.each(args, function(arg) { %>
         <tr>
-          <td valign="top" nowrap="true"><%= arg.link %></td>
+          <td valign="top" class="type" nowrap="true" rowspan="<%= (arg.comment ? 2 : 1) %>"><%= arg.link %></td>
           <td valign="top" class="var"><%= arg.name %></td>
+        </tr>
+        <tr>
           <td class="comment"><%= arg.comment %></td>
         </tr>
         <% }) %>
@@ -218,7 +220,7 @@ <h3>Argument in</h3>
 
     <!-- listing for an enum -->
     <script type="text/template" id="enum-template">
-      <h1 class="funcTitle"><%= type.tname %><small><%= type.type %></small></h1>
+      <h1 class="enumTitle"><%= type.tname %><small><%= type.type %></small></h1>
       <p><%= type.value %></p>
 
       <% if (type.data.description) { %>
@@ -228,24 +230,20 @@ <h1 class="funcTitle"><%= type.tname %><small><%= type.type %></small></h1>
       <p><%= type.data.comments %></p>
       <% } %>
 
-      <table>
+      <table class="enumTable">
         <% _.each(type.data.fields, function(field) { %>
         <tr>
-          <td><code><%= field.name %></code></td>
+          <td class="type"><code><%= field.name %></code></td>
+          <td class="comment"><%= field.comments %></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>
+      <h1 class="structTitle"><%= type.tname %><small><%= type.type %></small></h1>
       <p><%= type.value %></p>
 
       <% if (type.data.description) { %>
@@ -255,17 +253,17 @@ <h1 class="funcTitle"><%= type.tname %><small><%= type.type %></small></h1>
       <p><%= type.data.comments %></p>
       <% } %>
 
-      <table>
+      <table class="structTable">
         <% _.each(type.data.fields, function(field) { %>
           <tr>
-            <td><code><%= field.type %></code></td>
-            <td><code><%= field.name %></code></td>
-            <tr>
-          <% if (field.comments) { %>
+            <td class="type" valign="top" rowspan="<%= (field.comments ? 2 : 1) %>"><%= field.type %></td>
+            <td class="var"><%= field.name %></td>
+            <% if (field.comments) { %>
+          </tr>
           <tr>
-            <td colspan="2" class="type-comment"><%= field.comments %></td>
+            <td><span class="comment"><%= field.comments %></td>
+            <% } %>
           </tr>
-          <% } %>
         <% }) %>
       </table>
 

site/js/docurium.js

@@ -362,23 +362,12 @@ $(function() {
       var needs = _.map(data.used.needs, toPair, docurium)
       var fileLink = {name: data.file, url: docurium.github_file(data.file, data.line, data.lineto)}
 
-      // 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)
+      // Hot link our field types
+      data.fields = _.map(data.fields, function(field) {
+        return {type: this.hotLink(field.type), name: field.name, comments: field.comments}
+      }, docurium)
 
-      this.set('data', {tname: tname, data: data, blocks: blocks, returns: returns, needs: needs, fileLink: fileLink})
+      this.set('data', {tname: tname, data: data, returns: returns, needs: needs, fileLink: fileLink})
     }
   })
 

test/docurium_test.rb

@@ -152,11 +152,16 @@ def test_can_parse_function_cast_args
     assert_equal 'int (*)(const char *, void *)', func[:args][2][:type]
     assert_equal 'Function which will be called for every listed ref', func[:args][2][:comment]
     expect_comment =<<-EOF
-    <p>The listed references may be filtered by type, or using a bitwise OR of several types. Use the magic value <code>GIT_REF_LISTALL</code> to obtain all references, including packed ones.</p>
-
-    <p>The <code>callback</code> function will be called for each of the references in the repository, and will receive the name of the reference and the <code>payload</code> value passed to this method.</p>
+<p>The listed references may be filtered by type, or using
+ a bitwise OR of several types. Use the magic value
+ <code>GIT_REF_LISTALL</code> to obtain all references, including
+ packed ones.</p>
+
+<p>The <code>callback</code> function will be called for each of the references
+ in the repository, and will receive the name of the reference and
+ the <code>payload</code> value passed to this method.</p>
     EOF
-    assert_equal expect_comment.split("\n").map(&:strip), func[:comments].split("\n")
+    assert_equal expect_comment.split("\n"), func[:comments].split("\n")
   end
 
   def test_can_get_the_full_description_from_multi_liners

test/fixtures/git2/repository.h

@@ -212,6 +212,45 @@ GIT_EXTERN(const char *) git_repository_path(git_repository *repo);
  */
 GIT_EXTERN(const char *) git_repository_workdir(git_repository *repo);
 
+/**
+ * Extended options structure for `git_repository_init_ext`.
+ *
+ * This contains extra options for `git_repository_init_ext` that enable
+ * additional initialization features.  The fields are:
+ *
+ * * flags - Combination of GIT_REPOSITORY_INIT flags above.
+ * * mode  - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_...
+ *        constants above, or to a custom value that you would like.
+ * * workdir_path - The path to the working dir or NULL for default (i.e.
+ *        repo_path parent on non-bare repos).  IF THIS IS RELATIVE PATH,
+ *        IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH.  If this is not
+ *        the "natural" working directory, a .git gitlink file will be
+ *        created here linking to the repo_path.
+ * * description - If set, this will be used to initialize the "description"
+ *        file in the repository, instead of using the template content.
+ * * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set,
+ *        this contains the path to use for the template directory.  If
+ *        this is NULL, the config or default directory options will be
+ *        used instead.
+ * * initial_head - The name of the head to point HEAD at.  If NULL, then
+ *        this will be treated as "master" and the HEAD ref will be set
+ *        to "refs/heads/master".  If this begins with "refs/" it will be
+ *        used verbatim; otherwise "refs/heads/" will be prefixed.
+ * * origin_url - If this is non-NULL, then after the rest of the
+ *        repository initialization is completed, an "origin" remote
+ *        will be added pointing to this URL.
+ */
+typedef struct {
+	unsigned int version;
+	uint32_t    flags;
+	uint32_t    mode;
+	const char *workdir_path;
+	const char *description;
+	const char *template_path;
+	const char *initial_head;
+	const char *origin_url;
+} git_repository_init_options;
+
 /** @} */
 GIT_END_DECL
 #endif