[docs] Update docs about writing rules#2267
Conversation
Generated by 🚫 Danger |
4589dfb to
54b8ace
Compare
| {% jdoc_nspace :jrule java::lang.java.rule %} | ||
|
|
||
| {% include note.html content="TODO All that should be written in the Javadocs, | ||
| not sure we even need a doc page. Would be simpler to maintain too" %} |
There was a problem hiding this comment.
Honestly, I think, we need such docs - lots of examples actually. It's easier to learn from examples and a website is more accessible than javadocs - you would need to have a starting pointer anyway, so at least a minimalistic documentation is always needed IMHO...
| passed the nodes it is interested in. To use the rulechain correctly: | ||
| * Your rule must register those node types by calling {% jdoc core::Rule#addRuleChainVisit(java.lang.Class) %} | ||
| in its constructor. | ||
| * Your visit methods **must not recurse!** In effect, you should call never |
There was a problem hiding this comment.
For this case, we actually use a custom pmd rule: https://github.com/pmd/build-tools/blob/8434ea814f17e3b0fe1c56405b6673eb689d9c7c/src/main/resources/net/sourceforge/pmd/pmd-dogfood-config.xml#L583
Maybe it's worth that we ship this rule in the main distro (in an application specific ruleset), so that it can be used when developing rules for PMD...
| properties, you can do the initialization e.g. in the visit-method of the {% jdoc jast::ASTCompilationUnit %} | ||
| node - which is visited first and only once per file. However, this | ||
| solution would only work for rules written for the Java language. A language | ||
| independent way is to override the method `apply` of the rule (and call super). |
There was a problem hiding this comment.
I think, it's actually better to override the start(RuleContext) method, to do any initialization before a file is analyzed.
I'll change that...
| tags: [extending, userdocs] | ||
| summary: "Learn how to write a custom rule for PMD" | ||
| last_updated: July 3, 2016 | ||
| permalink: pmd_userdocs_extending_writing_pmd_rules.html |
There was a problem hiding this comment.
I'd keep this page, in case someone has a deep link to https://pmd.github.io/latest/pmd_userdocs_extending_writing_pmd_rules.html
I'll readd this page and provide links to the new pages you wrote.
| <td markdown="block"> | ||
|
|
||
| ```java | ||
| └─ CompilationUnit |
There was a problem hiding this comment.
This is generated by the designer :) You can choose to export a subtree to text
| language implementation provides a base rule class to ease your pain, | ||
| e.g. {% jdoc jrule::AbstractJavaRule %}. | ||
| 2. compile this class, linking it to PMD APIs (eg using PMD as a maven dependency) | ||
| 3. bundle this into a JAR and add it to the execution classpath of PMD |
There was a problem hiding this comment.
I some point, we might create a doc page about this -> https://github.com/pmd/pmd-examples
| summary: "Writing XPath rules for PMD" | ||
| last_updated: July 3, 2016 | ||
| summary: "This page describes XPath rule support in more details" | ||
| last_updated: July 2018 (6.6.0) |
There was a problem hiding this comment.
I'd simply use the latest timestamp, which is now February 2020 (6.22.0)
|
|
||
| The following expression does the magic we need: | ||
| {% render %} | ||
| {% include custom/xpath_fun_doc.html %} |
This is long overdue. The current page is all over the place and the examples don't even work anymore.
PropertyFactoryinstead of deprecated property types (this is due since PMD 6.10). I removed part of the doc because the Javadocs of PropertyFactory are nice enoughI updated the Gemlock but this could be reverted if you don't want it. It uses bundler 2 now
Wdyt?