From 7573fd94d988151bb9f7e6406e3735b42eee6e47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Fri, 5 Apr 2019 14:13:39 +0200 Subject: [PATCH] Use expandable row for xpath funs --- docs/_data/xpath_funs.yml | 25 ++++-- docs/_includes/custom/xpath_fun_doc.html | 98 ++++++++++++++++-------- docs/_plugins/custom_filters.rb | 31 ++++---- docs/css/pmd-customstyles.css | 24 ++++++ 4 files changed, 126 insertions(+), 52 deletions(-) diff --git a/docs/_data/xpath_funs.yml b/docs/_data/xpath_funs.yml index 404e749726..07f70a472f 100644 --- a/docs/_data/xpath_funs.yml +++ b/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`)" \ No newline at end of file + outcome: "Matches variable declarators of type `List` (but not e.g. `ArrayList`)" diff --git a/docs/_includes/custom/xpath_fun_doc.html b/docs/_includes/custom/xpath_fun_doc.html index 1fe1ca896d..e56f97b9ef 100644 --- a/docs/_includes/custom/xpath_fun_doc.html +++ b/docs/_includes/custom/xpath_fun_doc.html @@ -6,57 +6,93 @@ {{ lang.name }} functions are in the namespace `{{ lang.ns }}`. -
- +
+
- - + {% 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 %} - + + - - diff --git a/docs/_plugins/custom_filters.rb b/docs/_plugins/custom_filters.rb index 922071297c..2b3067e21a 100644 --- a/docs/_plugins/custom_filters.rb +++ b/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)] diff --git a/docs/css/pmd-customstyles.css b/docs/css/pmd-customstyles.css index db83a50f50..ae1bfcd073 100644 --- a/docs/css/pmd-customstyles.css +++ b/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; +}
Function nameParameters DescriptionNotes
{{ fun.name }}{{ fun.shortDescription }} - {% 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 %} -
    - {% for i in 0..fun.parameters.size %} - {{ assign param = fun.parameters[i] }} -
  • {{ i + 1 }} : {{ param.description }}
    • - {% endfor %} -
- {% endif %} - 		{{ fun.description }} - {% if fun.notes_are_same_as %} - (Same as for `{{ fun.notes_are_same_as }}`) - {% else %} - {{ fun.notes }} - {% endif %} +
-
-

{{ fun.name }}

-

This is a fun function

+
+ +
+ +

+ {{ lang.ns | append: ':' }}{{ fun.name }}{{ fun | xpath_fun_type }} +

+ +
+ +
+
{{ fun.description }}
+
Remarks
+
{{ fun.notes }}
+ + {% unless fun.parameters.size == 0 %} + +
Parameters
+ +
+
+
+ {% for param in fun.parameters %} +
+ {{ param.name }} + as {{ param.type }} +
+
{{ param.description }}
+ {% endfor %} +
+
+
+ + {% endunless %} + + {% unless fun.examples.size == 0 %} + +
+ + +
Examples
+ + + + {% for example in fun.examples %} + + + + + + + {% endfor %} +
{{ example.code }}{{ example.description }}
+ + {% endunless %} +
+