Use expandable row for xpath funs

docs/_data/xpath_funs.yml

@@ -1,27 +1,36 @@
+aliases:
+  - &qname_param
+    name: javaQualifiedName
+    type: "xs:string"
+    description: "The qualified name of a class, possibly with pairs of brackets to indicate an array type.
+                  Can also be a primitive type name."
+  - &needs_typenode "The context node must be a {% jdoc jast::TypeNode %}"
+
 langs:
   - name: "Java"
     ns: "pmd-java"
     funs:
       - name: typeIs
         returnType: "xs:boolean"
+        shortDescription: "Tests a node's static type"
         description: "Returns true if the context node's static type is a subtype of the given type"
-        notes: "The context node must be a {% jdoc jast::TypeNode %}"
+        notes: *needs_typenode
         parameters:
-          - name: javaQualifiedName
-            type: "xs:string"
-            description: "the qualified name of a class, possibly with pairs of brackets to indicate an array type.
-              Can also be a primitive type name."
+          - *qname_param
 
       - name: typeIsExactly
         returnType: "xs:boolean"
+        shortDescription: "Tests a node's static type, ignoring subtypes"
         description: "Returns true if the context node's static type is exactly the given type.
                       In particular, returns false if the context node's type is
                       a subtype of the given type."
-        notes_are_same_as: typeIs
-        params_are_same_as: typeIs
+        notes: *needs_typenode
+        parameters:
+          - *qname_param
 
       - name: metric
         returnType: "xs:decimal?"
+        shortDescription: "Computes and returns the value of a metric"
         description: "Returns the value of the metric as evaluated on the context node"
         notes: "The context node must be a {% jdoc jast::ASTAnyTypeDeclaration %} or a {% jdoc jast::MethodLikeNode %}"
         parameters:
@@ -35,4 +44,4 @@ langs:
       - code: '//VariableDeclaratorId[pmd-java:typeIs("java.lang.List")]'
         outcome: "Matches variable declarators of type `List` or any of its subtypes (including e.g. `ArrayList`)"
       - code: '//VariableDeclaratorId[pmd-java:typeIsExactly("java.lang.List")]'
-        outcome: "Matches variable declarators of type `List` (but not e.g. `ArrayList`)"
+        outcome: "Matches variable declarators of type `List` (but not e.g. `ArrayList`)"

docs/_includes/custom/xpath_fun_doc.html

@@ -6,57 +6,93 @@
 
 {{ lang.name }} functions are in the namespace `{{ lang.ns }}`.
 
-<div class="table-responsive" style="border-collapse:collapse;">
-    <table>
+<div class="table-responsive">
+    <table width="100%">
 
         <thead>
         <tr>
             <th>Function name</th>
-            <th>Parameters</th>
             <th>Description</th>
-            <th>Notes</th>
+            <th></th>
         </tr>
         </thead>
 
 
         {% for fun in lang.funs %}
 
-        {% capture fun_id %}{{ lang.ns | append: '-' | append: fun.name | pp }}{% endcapture %}
+        {% capture fun_id %}{{ lang.ns | append: '-' | append: fun.name }}{% endcapture %}
 
-        <tr data-toggle="collapse" data-target="{{ fun_id | prepend: '#' }}" class="accordion-toggle">
+        <tr data-toggle="collapse" id="{{ fun_id }}" data-target="{{ fun_id | prepend: '#' | append: '-expand' }}" class="accordion-toggle">
 
             <td>{{ fun.name }}</td>
+            <td>{{ fun.shortDescription }}</td>
             <td>
-                {% if fun.parameters.size == 0 %}
-                    None
-                {% elsif fun.params_are_same_as %}
-                    (Same as for `{{ fun.params_are_same_as }}`)
-                {% elsif fun.parameters.size == 1 %}
-                    1: {{ fun.parameters[0].description }}
-                {% else %}
-                <ul>
-                    {% for i in 0..fun.parameters.size %}
-                    {{ assign param = fun.parameters[i] }}
-                    <li>{{ i + 1 }} : {{ param.description }}</li>
-                    {% endfor %}
-                </ul>
-                {% endif %}
-            </td>
-            <td>{{ fun.description }}</td>
-            <td>
-                {% if fun.notes_are_same_as %}
-                    (Same as for `{{ fun.notes_are_same_as }}`)
-                {% else %}
-                    {{ fun.notes }}
-                {% endif %}
+                <button type="button" class="btn btn-link"><i
+                        class="fa fa-ellipsis-h"></i></button>
             </td>
         </tr>
 
         <tr>
             <td colspan="4" class="hiddenRow">
-                <div class="accordion-body collapse" id="{{ fun_id }}">
-                    <h4>{{ fun.name }}</h4>
-                    <p>This is a fun function</p>
+                <div class="accordion-body collapse" id="{{ fun_id | append: '-expand' }}">
+
+                    <div style="margin-left: 15px" class="xpath-fun-doc">
+
+                        <h4 class="fun-details-header">
+                            <span class="fun-ns">{{ lang.ns | append: ':' }}</span><span
+                                class="fun-name">{{ fun.name }}</span><span
+                                class="fun-ns">{{ fun | xpath_fun_type }}</span>
+                        </h4>
+
+                        <div style="margin-left: 30px">
+
+                            <dl>
+                                <dd>{{ fun.description }}</dd>
+                                <dt>Remarks</dt>
+                                <dd>{{ fun.notes }}</dd>
+
+                                {% unless fun.parameters.size == 0 %}
+
+                                <dt>Parameters</dt>
+
+                                <dd>
+                                    <div style="margin-left: 20px">
+                                        <dl>
+                                            {% for param in fun.parameters %}
+                                            <dt>
+                                                <span class="param-name">{{ param.name }}</span>
+                                                <span class="param-type"> as {{ param.type }}</span>
+                                            </dt>
+                                            <dd>{{ param.description }}</dd>
+                                            {% endfor %}
+                                        </dl>
+                                    </div>
+                                </dd>
+
+                                {% endunless %}
+
+                                {% unless fun.examples.size == 0 %}
+
+                            </dl>
+
+
+                            <h5>Examples</h5>
+
+                            <table>
+
+                                {% for example in fun.examples %}
+
+                                <tr>
+                                    <td><code>{{ example.code }}</code></td>
+                                    <td>{{ example.description }}</td>
+                                </tr>
+
+                                {% endfor %}
+                            </table>
+
+                            {% endunless %}
+                        </div>
+                    </div>
                 </div>
             </td>
         </tr>

docs/_plugins/custom_filters.rb

@@ -44,16 +44,23 @@ module CustomFilters
 
   end
 
+  def xpath_fun_type(fun_yaml)
+
+    res = '('
+
+    params = fun_yaml['parameters']
+
+    res += params.map {|it| it['type']}.join(', ') if params
+
+    res + ') as ' + fun_yaml['returnType']
+  end
+
   def regex_replace(str, regex, subst)
-    if str && regex
-      str.gsub(Regexp::new(regex), subst || "")
-    end
+    str.gsub(Regexp.new(regex), subst || '') if str && regex
   end
 
   def regex_split(str, regex = nil)
-    if str
-      str.split(regex && Regexp::new(regex))
-    end
+    str.split(regex && Regexp.new(regex)) if str
   end
 
   # Takes an array of strings and maps every element x to {{ x | append: suffix }}
@@ -63,9 +70,7 @@ module CustomFilters
 
   # Returns the initial argument only if the second argument is truthy
   def keep_if(any, test)
-    if test
-      any
-    end
+    any if test
   end
 
   # Append the suffix only if the condition argument is truthy
@@ -100,9 +105,9 @@ module CustomFilters
 
   def flatten_rec(seq)
     seq.map {|h|
-      if (subs = h["folderitems"] || h["subfolderitems"] || h["subfolders"])
+      if (subs = h['folderitems'] || h['subfolderitems'] || h['subfolders'])
         flatten_rec(subs).flatten
-      elsif (page = h["url"])
+      elsif (page = h['url'])
         page
       end
     }.flatten
@@ -110,10 +115,10 @@ module CustomFilters
 
   def rank_lookup_from_sidebar(sidebar)
 
-    folders = sidebar["entries"][0]["folders"]
+    folders = sidebar['entries'][0]['folders']
 
     ordered = flatten_rec(folders).select {|url|
-      url && url.end_with?(".html")
+      url && url.end_with?('.html')
     }
 
     Hash[ordered.zip (0...ordered.size)]

docs/css/pmd-customstyles.css

@@ -57,3 +57,27 @@ details[open] summary {
 .hiddenRow {
     padding: 0 !important;
 }
+
+.xpath-fun-doc .fun-name {
+    font-weight: bold;
+}
+
+.xpath-fun-doc .fun-details-header {
+    font-family: monospace;
+    font-size: larger;
+}
+
+.xpath-fun-doc .fun-ns {
+    color: darkgray;
+}
+
+.xpath-fun-doc span.param-name {
+    font-weight: normal;
+
+}
+
+.xpath-fun-doc span.param-type {
+    font-weight: lighter;
+    font-style: italic;
+    color: darkgray;
+}