diff --git a/docs/_data/xpath_funs.yml b/docs/_data/xpath_funs.yml index 2b56bfb2bf..222f3b70f2 100644 --- a/docs/_data/xpath_funs.yml +++ b/docs/_data/xpath_funs.yml @@ -1,3 +1,6 @@ +# This file describes custom XPath functions per language +# This is rendered using _includes/custom/xpath_fun_doc.html + aliases: - &qname_param name: javaQualifiedName diff --git a/docs/_includes/custom/faq_entry.html b/docs/_includes/custom/faq_entry.html deleted file mode 100644 index 1cbb2560ec..0000000000 --- a/docs/_includes/custom/faq_entry.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -{% assign panel_id = 8 | random_alphabetic %} - -
-
-

- {{ include.question | render_markdown }} -

-
-
-
- {{ include.answer | render_markdown }} -
-
-
\ No newline at end of file diff --git a/docs/_plugins/render_block.rb b/docs/_plugins/render_block.rb index 49f3fa8cfb..111f01ab76 100644 --- a/docs/_plugins/render_block.rb +++ b/docs/_plugins/render_block.rb @@ -1,6 +1,5 @@ -require 'pp' # -# Tags to create a complex object inline in JSON. +# Apply a second pass of rendering on a block # class RenderBlock < Liquid::Block diff --git a/docs/images/userdocs/designer-overview-with-nums.png b/docs/images/userdocs/designer-overview-with-nums.png index a6e2eb386f..2851fd8ae6 100644 Binary files a/docs/images/userdocs/designer-overview-with-nums.png and b/docs/images/userdocs/designer-overview-with-nums.png differ diff --git a/docs/images/userdocs/designer-overview.png b/docs/images/userdocs/designer-overview.png new file mode 100644 index 0000000000..8cbda3c4d5 Binary files /dev/null and b/docs/images/userdocs/designer-overview.png differ diff --git a/docs/pages/pmd/userdocs/extending/defining_properties.md b/docs/pages/pmd/userdocs/extending/defining_properties.md index aa24312f13..82892447ed 100644 --- a/docs/pages/pmd/userdocs/extending/defining_properties.md +++ b/docs/pages/pmd/userdocs/extending/defining_properties.md @@ -189,3 +189,4 @@ the sequence *contains* `@Image`. That is, the above rule will report all variab named `foo` or `bar`. All other XPath 2.0 [functions operating on sequences](https://www.w3.org/TR/xpath-functions/#sequence-functions) are supported. +{%include tip.html content="You can also [define properties directly in the designer](pmd-userdocs_designer_reference.html#rule-properties)" %} diff --git a/docs/pages/pmd/userdocs/extending/writing_rules_intro.md b/docs/pages/pmd/userdocs/extending/writing_rules_intro.md index 24c753d217..20f4147b20 100644 --- a/docs/pages/pmd/userdocs/extending/writing_rules_intro.md +++ b/docs/pages/pmd/userdocs/extending/writing_rules_intro.md @@ -1,5 +1,5 @@ --- -title: Intro to writing PMD rules +title: Introduction to writing PMD rules tags: [extending, userdocs, getting_started] summary: "Writing your own PMD rules TODO" last_updated: July 2018 (6.6.0) @@ -7,15 +7,14 @@ permalink: pmd_userdocs_extending_writing_rules_intro.html author: Clément Fournier --- - -## Why write custom rules? - -TODO +PMD is a framework to perform code analysis. You can create your own rules to +check for patterns specific to your codebase, or the coding practices of your +team. ## How rules work: the AST Before running rules, PMD parses the source file into a data structure called an -*abstract syntax tree* (AST). This tree represents the syntactic structure of the +**abstract syntax tree (AST)**. This tree represents the syntactic structure of the code, and encodes syntactic relations between source code elements. For instance, in Java, method declarations belong to a class: in the AST, the nodes representing method declarations will be descendants of a node representing the declaration of @@ -74,7 +73,9 @@ Each PMD language has its own set of such classes, and its own rules about how these classes relate to one another, based on the grammar of the language. For example, all Java AST nodes extend {% jdoc java::lang.java.ast.JavaNode %}. -The structure of the AST can be discovered by using the [Rule Designer](pmd_userdocs_extending_designer_reference.html). +The structure of the AST can be discovered through + * the [Rule Designer](pmd_userdocs_extending_designer_reference.html#ast-inspection) + * the [AST dump feature](pmd_devdocs_experimental_ast_dump.html) diff --git a/docs/pages/pmd/userdocs/extending/your_first_rule.md b/docs/pages/pmd/userdocs/extending/your_first_rule.md index 27dba388cf..acec128716 100644 --- a/docs/pages/pmd/userdocs/extending/your_first_rule.md +++ b/docs/pages/pmd/userdocs/extending/your_first_rule.md @@ -140,24 +140,3 @@ TODO You can notice that your XPath expression ends up inside a [property](pmd_userdocs_configuring_rules.html#rule-properties) of a rule of type XPathRule, which is how XPath rules are implemented. - -### Defining rule properties - -Some time later, your boss' boss decides he doesn't want to be called short in Java -too, and would like you to add him to the rule. There are several ways to do that, -but you decide to use a rule property to make your rule extensible. Doing that -directly in the XML is [explained on that page](pmd_userdocs_extending_defining_properties.html#for-xpath-rules), - and we'll explain here how to do that in the designer. - -The table to the left of the zone (3) in the screenshot above is a list of -properties defined for your rule. -Right-clicking the table and selecting "Add property..", you may add a property of -type `List[String]` to represent your boss names. You can then use it in your XPath -query with a dollar prefix, i.e. - -```xpath -//VariableDeclaratorId[@Image = $bossNames and ../../Type[@TypeImage = "short"]] -``` - - -{% include note.html content="Using a property of type `List[String]` requires you to use XPath 2.0" %}