hiifong/pmd
1
0
Fork 0
forked from phoedos/pmd
Code Pull Requests Activity
pmd/pmd_devdocs_writing_documentation.html

2229 lines
59 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content="devdocs, documentation, jekyll, markdown">
<title>Writing documentation | PMD Source Code Analyzer</title>
<link rel="stylesheet" type="text/css" href="assets/fontawesome-free-5.15.4-web/css/all.min.css">
<link rel="stylesheet" type="text/css" href="assets/bootstrap-4.5.2-dist/css/bootstrap.min.css">
<link rel="stylesheet" type="text/css" href="css/syntax.css">
<link rel="stylesheet" type="text/css" href="css/modern-business.css">
<link rel="stylesheet" type="text/css" href="css/customstyles.css">
<link rel="stylesheet" type="text/css" href="css/theme-green.css">
<link rel="stylesheet" type="text/css" href="css/pmd-customstyles.css">
<link rel="shortcut icon" href="images/logo/favicon.ico" type="image/x-icon">
<link rel="icon" href="images/logo/favicon.ico" type="image/x-icon">
<link rel="alternate" type="application/rss+xml" title="" href="feed.xml">
</head>
<body>
<!-- Content is offset by the height of the topnav bar. -->
<!-- There's already a padding-top rule in modern-business.css, but it apparently doesn't work on Firefox 60 and Chrome 67 -->
<div id="topbar-content-offset">
<!-- Navigation -->
<nav class="navbar navbar-expand-lg fixed-top navbar-dark">
<div class="container topnavlinks">
<a class="navbar-brand fas fa-home fa-lg" href="index.html">&nbsp;<span class="projectTitle"> PMD Source Code Analyzer Project</span></a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto mt-2 mt-lg-0"></ul>
<ul class="navbar-nav">
<!-- toggle sidebar button -->
<li class="nav-item"><a id="tg-sb-link" class="nav-link" href="#"><i id="tg-sb-icon" class="fas fa-toggle-on"></i> Nav</a></li>
<!-- entries without drop-downs appear here -->
<li class="nav-item"><a class="nav-link" href="https://github.com/pmd/pmd/releases/latest" target="_blank">Download</a></li>
<li class="nav-item"><a class="nav-link" href="https://github.com/pmd/pmd" target="_blank">Fork us on github</a></li>
<!-- entries with drop-downs appear here -->
<!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
</ul>
<form class="form-inline my-2 my-lg-0">
<input class="form-control mr-sm-2" type="search" placeholder="search..." id="search-input">
<ul id="results-container"></ul>
</form>
</div>
</div>
</nav>
<!-- Page Content -->
<div class="container-toc-wrapper">
<div class="container">
<div class="col-lg-12">&nbsp;</div>
<!-- Content Row -->
<div class="row">
<!-- Sidebar Column -->
<div class="col-md-3" id="tg-sb-sidebar">
<ul id="mysidebar" class="nav">
<li class="sidebarTitle">PMD 7.4.0-SNAPSHOT</li>
<div class="sidebarTitleDate">Release date: 26-July-2024</div>
<li>
<a href="#">About</a>
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="pmd_release_notes.html">Release notes</a></li>
<li><a href="pmd_release_notes_pmd7.html">Release notes (PMD 7)</a></li>
<li><a href="pmd_about_help.html">Getting help</a></li>
<li><a href="pmd_about_release_policies.html">Release policies</a></li>
<li><a href="pmd_about_support_lifecycle.html">Support lifecycle</a></li>
</ul>
</li>
<li>
<a href="#">User Documentation</a>
<ul>
<li><a href="pmd_userdocs_migrating_to_pmd7.html">Migration Guide for PMD 7</a></li>
<li><a href="pmd_userdocs_installation.html">Installation and basic CLI usage</a></li>
<li><a href="pmd_userdocs_making_rulesets.html">Making rulesets</a></li>
<li><a href="pmd_userdocs_configuring_rules.html">Configuring rules</a></li>
<li><a href="pmd_userdocs_best_practices.html">Best practices</a></li>
<li><a href="pmd_userdocs_suppressing_warnings.html">Suppressing warnings</a></li>
<li><a href="pmd_userdocs_incremental_analysis.html">Incremental analysis</a></li>
<li><a href="pmd_userdocs_cli_reference.html">PMD CLI reference</a></li>
<li><a href="pmd_userdocs_report_formats.html">PMD Report formats</a></li>
<li><a href="pmd_userdocs_3rdpartyrulesets.html">3rd party rulesets</a></li>
<li class="subfolders">
<a href="#">CPD reference</a>
<ul>
<li><a href="pmd_userdocs_cpd.html">Copy-paste detection</a></li>
<li><a href="pmd_userdocs_cpd_report_formats.html">CPD Report formats</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Extending PMD</a>
<ul>
<li><a href="pmd_userdocs_extending_writing_rules_intro.html">Introduction to writing rules</a></li>
<li><a href="pmd_userdocs_extending_your_first_rule.html">Your first rule</a></li>
<li><a href="pmd_userdocs_extending_writing_xpath_rules.html">XPath rules</a></li>
<li><a href="pmd_userdocs_extending_writing_java_rules.html">Java rules</a></li>
<li><a href="pmd_userdocs_extending_designer_reference.html">Rule designer reference</a></li>
<li><a href="pmd_userdocs_extending_defining_properties.html">Defining rule properties</a></li>
<li><a href="pmd_userdocs_extending_rule_guidelines.html">Rule guidelines</a></li>
<li><a href="pmd_userdocs_extending_testing.html">Testing your rules</a></li>
<li><a href="pmd_userdocs_extending_ast_dump.html">Creating (XML) dump of the AST</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Tools / Integrations</a>
<ul>
<li><a href="pmd_userdocs_tools_maven.html">Maven PMD Plugin</a></li>
<li><a href="pmd_userdocs_tools_gradle.html">Gradle</a></li>
<li><a href="pmd_userdocs_tools_ant.html">Ant</a></li>
<li><a href="pmd_userdocs_tools_java_api.html">PMD Java API</a></li>
<li><a href="pmd_userdocs_tools_bld.html">bld PMD Extension</a></li>
<li><a href="pmd_userdocs_tools_ci.html">CI integrations</a></li>
<li><a href="pmd_userdocs_tools.html">Other Tools / Integrations</a></li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#">Rule Reference</a>
<ul>
<li class="subfolders">
<a href="#">Apex Rules</a>
<ul>
<li><a href="pmd_rules_apex.html">Index</a></li>
<li><a href="pmd_rules_apex_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_apex_codestyle.html">Code Style</a></li>
<li><a href="pmd_rules_apex_design.html">Design</a></li>
<li><a href="pmd_rules_apex_documentation.html">Documentation</a></li>
<li><a href="pmd_rules_apex_errorprone.html">Error Prone</a></li>
<li><a href="pmd_rules_apex_performance.html">Performance</a></li>
<li><a href="pmd_rules_apex_security.html">Security</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">HTML Rules</a>
<ul>
<li><a href="pmd_rules_html.html">Index</a></li>
<li><a href="pmd_rules_html_bestpractices.html">Best Practices</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Java Rules</a>
<ul>
<li><a href="pmd_rules_java.html">Index</a></li>
<li><a href="pmd_rules_java_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_java_codestyle.html">Code Style</a></li>
<li><a href="pmd_rules_java_design.html">Design</a></li>
<li><a href="pmd_rules_java_documentation.html">Documentation</a></li>
<li><a href="pmd_rules_java_errorprone.html">Error Prone</a></li>
<li><a href="pmd_rules_java_multithreading.html">Multithreading</a></li>
<li><a href="pmd_rules_java_performance.html">Performance</a></li>
<li><a href="pmd_rules_java_security.html">Security</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Java Server Pages Rules</a>
<ul>
<li><a href="pmd_rules_jsp.html">Index</a></li>
<li><a href="pmd_rules_jsp_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_jsp_codestyle.html">Code Style</a></li>
<li><a href="pmd_rules_jsp_design.html">Design</a></li>
<li><a href="pmd_rules_jsp_errorprone.html">Error Prone</a></li>
<li><a href="pmd_rules_jsp_security.html">Security</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">JavaScript Rules</a>
<ul>
<li><a href="pmd_rules_ecmascript.html">Index</a></li>
<li><a href="pmd_rules_ecmascript_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_ecmascript_codestyle.html">Code Style</a></li>
<li><a href="pmd_rules_ecmascript_errorprone.html">Error Prone</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Kotlin Rules</a>
<ul>
<li><a href="pmd_rules_kotlin.html">Index</a></li>
<li><a href="pmd_rules_kotlin_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_kotlin_errorprone.html">Error Prone</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Maven POM Rules</a>
<ul>
<li><a href="pmd_rules_pom.html">Index</a></li>
<li><a href="pmd_rules_pom_errorprone.html">Error Prone</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Modelica Rules</a>
<ul>
<li><a href="pmd_rules_modelica.html">Index</a></li>
<li><a href="pmd_rules_modelica_bestpractices.html">Best Practices</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">PLSQL Rules</a>
<ul>
<li><a href="pmd_rules_plsql.html">Index</a></li>
<li><a href="pmd_rules_plsql_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_plsql_codestyle.html">Code Style</a></li>
<li><a href="pmd_rules_plsql_design.html">Design</a></li>
<li><a href="pmd_rules_plsql_errorprone.html">Error Prone</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Salesforce Visualforce Rules</a>
<ul>
<li><a href="pmd_rules_visualforce.html">Index</a></li>
<li><a href="pmd_rules_visualforce_security.html">Security</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Scala Rules</a>
<ul>
<li><a href="pmd_rules_scala.html">Index</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Swift Rules</a>
<ul>
<li><a href="pmd_rules_swift.html">Index</a></li>
<li><a href="pmd_rules_swift_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_swift_errorprone.html">Error Prone</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Velocity Template Language (VTL) Rules</a>
<ul>
<li><a href="pmd_rules_velocity.html">Index</a></li>
<li><a href="pmd_rules_velocity_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_velocity_design.html">Design</a></li>
<li><a href="pmd_rules_velocity_errorprone.html">Error Prone</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">WSDL Rules</a>
<ul>
<li><a href="pmd_rules_wsdl.html">Index</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">XML Rules</a>
<ul>
<li><a href="pmd_rules_xml.html">Index</a></li>
<li><a href="pmd_rules_xml_bestpractices.html">Best Practices</a></li>
<li><a href="pmd_rules_xml_errorprone.html">Error Prone</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">XSL Rules</a>
<ul>
<li><a href="pmd_rules_xsl.html">Index</a></li>
<li><a href="pmd_rules_xsl_codestyle.html">Code Style</a></li>
<li><a href="pmd_rules_xsl_performance.html">Performance</a></li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#">Language-Specific Documentation</a>
<ul>
<li><a href="pmd_languages_index.html">Overview</a></li>
<li><a href="pmd_languages_configuration.html">Language configuration</a></li>
<li><a href="pmd_languages_apex.html">Apex</a></li>
<li><a href="pmd_languages_cpp.html">C/C++</a></li>
<li><a href="pmd_languages_cs.html">C#</a></li>
<li><a href="pmd_languages_coco.html">Coco</a></li>
<li><a href="pmd_languages_dart.html">Dart</a></li>
<li><a href="pmd_languages_fortran.html">Fortran</a></li>
<li><a href="pmd_languages_gherkin.html">Gherkin</a></li>
<li><a href="pmd_languages_go.html">Go</a></li>
<li><a href="pmd_languages_html.html">HTML</a></li>
<li><a href="pmd_languages_java.html">Java</a></li>
<li><a href="pmd_languages_js_ts.html">JavaScript / TypeScript</a></li>
<li><a href="pmd_languages_jsp.html">JSP</a></li>
<li><a href="pmd_languages_julia.html">Julia</a></li>
<li><a href="pmd_languages_kotlin.html">Kotlin</a></li>
<li><a href="pmd_languages_lua.html">Lua</a></li>
<li><a href="pmd_languages_matlab.html">Matlab</a></li>
<li><a href="pmd_languages_modelica.html">Modelica</a></li>
<li><a href="pmd_languages_objectivec.html">Objective-C</a></li>
<li><a href="pmd_languages_perl.html">Perl</a></li>
<li><a href="pmd_languages_php.html">PHP</a></li>
<li><a href="pmd_languages_plsql.html">PLSQL</a></li>
<li><a href="pmd_languages_python.html">Python</a></li>
<li><a href="pmd_languages_ruby.html">Ruby</a></li>
<li><a href="pmd_languages_scala.html">Scala</a></li>
<li><a href="pmd_languages_swift.html">Swift</a></li>
<li><a href="pmd_languages_tsql.html">T-SQL</a></li>
<li><a href="pmd_languages_visualforce.html">Visualforce</a></li>
<li><a href="pmd_languages_velocity.html">Velocity Template Language (VTL)</a></li>
<li><a href="pmd_languages_xml.html">XML and XML dialects</a></li>
</ul>
</li>
<li>
<a href="#">Developer Documentation</a>
<ul>
<li><a href="pmd_devdocs_development.html">Developer resources</a></li>
<li><a href="pmd_devdocs_building.html">Building PMD from source</a></li>
<li><a href="https://github.com/pmd/pmd/blob/master/CONTRIBUTING.md" target="_blank">Contributing</a></li>
<li class="active"><a href="pmd_devdocs_writing_documentation.html">Writing documentation</a></li>
<li><a href="pmd_devdocs_roadmap.html">Roadmap</a></li>
<li><a href="pmd_devdocs_how_pmd_works.html">How PMD works</a></li>
<li><a href="pmd_devdocs_pmdtester.html">Pmdtester</a></li>
<li><a href="pmd_devdocs_rule_deprecation_policy.html">Rule Deprecation Policy</a></li>
<li class="subfolders">
<a href="#">Major contributions</a>
<ul>
<li><a href="pmd_devdocs_major_rule_guidelines.html">Rule Guidelines</a></li>
<li><a href="pmd_devdocs_major_adding_new_language_javacc.html">Adding a new language (JavaCC)</a></li>
<li><a href="pmd_devdocs_major_adding_new_language_antlr.html">Adding a new language (ANTLR)</a></li>
<li><a href="pmd_devdocs_major_adding_new_cpd_language.html">Adding a new CPD language</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#">Experimental features</a>
<ul>
<li><a href="tag_experimental.html">List of experimental Features</a></li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#">Project documentation</a>
<ul>
<li class="subfolders">
<a href="#">Trivia about PMD</a>
<ul>
<li><a href="pmd_projectdocs_trivia_news.html">PMD in the press</a></li>
<li><a href="pmd_projectdocs_trivia_products.html">Products & books related to PMD</a></li>
<li><a href="pmd_projectdocs_trivia_similarprojects.html">Similar projects</a></li>
<li><a href="pmd_projectdocs_trivia_meaning.html">What does 'PMD' mean?</a></li>
</ul>
</li>
<li><a href="pmd_projectdocs_logo.html">Logo</a></li>
<li><a href="pmd_projectdocs_faq.html">FAQ</a></li>
<li><a href="license.html">License</a></li>
<li><a href="pmd_projectdocs_credits.html">Credits</a></li>
<li><a href="pmd_release_notes_old.html">Old release notes</a></li>
<li><a href="pmd_projectdocs_decisions.html">Decisions</a></li>
<li class="subfolders">
<a href="#">Project management</a>
<ul>
<li><a href="pmd_projectdocs_committers_infrastructure.html">Infrastructure</a></li>
<li><a href="pmd_projectdocs_committers_releasing.html">Release process</a></li>
<li><a href="pmd_projectdocs_committers_merging_pull_requests.html">Merging pull requests</a></li>
<li><a href="pmd_projectdocs_committers_main_landing_page.html">Main Landing page</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<!-- Content Column -->
<div class="col-md-9" id="tg-sb-content">
<header>
<div class="row">
<div class="col-lg-12">
<a href="./" role="button"
><i class="fa fa-home fa-lg"></i
></a>
» Writing documentation
<a
target="_blank"
href="https://github.com/pmd/pmd/blob/master/docs/pages/pmd/devdocs/writing_documentation.md"
class="float-right"
role="button"
><i class="fab fa-github fa-lg"></i> Edit on GitHub</a
>
</div>
</div>
<hr />
</header>
<div class="post-header">
<h1 class="post-title-main">Writing documentation</h1>
</div>
<div class="post-content" data-github-edit-url="https://github.com/pmd/pmd/blob/master/docs/pages/pmd/devdocs/writing_documentation.md">
<details id="inline-toc-details">
<summary>Table of Contents</summary>
<div id="inline-toc"><!-- empty, move TOC here when screen size too small --></div>
</details>
<p>PMD’s documentation uses <a href="https://jekyllrb.com/">Jekyll</a> with
the <a href="http://idratherbewriting.com/documentation-theme-jekyll/index.html">I’d rather be writing Jekyll Theme</a>.</p>
<p>Here are some quick tips.</p>
<h2 id="format">Format</h2>
<p>The pages are in general in <a href="https://kramdown.gettalong.org/parser/gfm.html">Github Flavored Markdown</a>.</p>
<h2 id="structure">Structure</h2>
<p>The documentation sources can be found in two places based on how they are generated:</p>
<ul>
<li>the ones that are manually written (like the one you are reading);</li>
<li>and the ones that are generated automatically from the category files. All the rule documentation
pages are generated that way.</li>
</ul>
<h3 id="handwritten-documentation">Handwritten documentation</h3>
<p>All handwritten documentation is stored in the subfolders under <code class="language-plaintext highlighter-rouge">docs/pages</code>. The folder structure resembles the sidebar structure.
Since all pages use a simple <em>permalink</em>, in the rendered html pages, all pages are flattened in one directory.
This makes it easy to view the documentation also offline.</p>
<h3 id="rule-documentation">Rule documentation</h3>
<p>The categories for a language <code class="language-plaintext highlighter-rouge">%lang%</code> are located in
<code class="language-plaintext highlighter-rouge">pmd-%lang%/src/main/resources/category/%lang% </code>. So for Java the categories
can be found under <a href="https://github.com/pmd/pmd/tree/master/pmd-java/src/main/resources/category/java">pmd-java/src/main/resources/category/java</a>.
The XML category files in this directory are transformed during build into markdown pages
describing the rules they contain. These pages are placed under <code class="language-plaintext highlighter-rouge">docs/</code> like the handwritten
documentation, and are then rendered with Jekyll like the rest of them. The rule documentation
generator is the separate submodule <code class="language-plaintext highlighter-rouge">pmd-doc</code>.</p>
<p>Modifying the documentation of a rule should thus not be done on the markdown page,
but directly on the XML <code class="language-plaintext highlighter-rouge">rule</code> tag corresponding to the rule, in the relevant
category file.</p>
<p>The XML documentation of rules can contain GitHub flavoured markdown.
Just wrap the markdown inside CDATA section in the xml. CDATA sections preserve
all formatting inside the delimiters, and allow to write code samples without
escaping special xml characters. For example:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;rule ...&gt;
&lt;description&gt;
&lt;![CDATA[
Full description, can contain markup
And paragraphs
]]&gt;
&lt;/description&gt;
...
&lt;/rule&gt;
</code></pre></div></div>
<h2 id="custom-liquid-tags">Custom Liquid Tags</h2>
<p>We have some additional custom liquid tags that help in writing the documentation.</p>
<p>Here’s a short overview:</p>
<table>
<thead>
<tr>
<th style="text-align: left">Liquid</th>
<th style="text-align: left">Rendered as</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% rule "java/codestyle/LinguisticNaming" %}</code></td>
<td style="text-align: left"><a href="pmd_rules_java_codestyle.html#linguisticnaming"><code class="language-plaintext highlighter-rouge">LinguisticNaming</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc core::lang.rule.Rule %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/rule/Rule.html#"><code>Rule</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc !q!core::lang.rule.Rule %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/rule/Rule.html#"><code>net.sourceforge.pmd.lang.rule.Rule</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc core::lang.rule.Rule#setName(java.lang.String) %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/rule/Rule.html#setName(java.lang.String)"><code>setName</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc !c!core::lang.rule.Rule#setName(java.lang.String) %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/rule/Rule.html#setName(java.lang.String)"><code>Rule#setName</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc !a!core::lang.rule.Rule#setName(java.lang.String) %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/rule/Rule.html#setName(java.lang.String)"><code>setName(String)</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc !ac!core::lang.rule.Rule#setName(java.lang.String) %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/rule/Rule.html#setName(java.lang.String)"><code>Rule#setName(String)</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc core::properties.PropertyDescriptor %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/properties/PropertyDescriptor.html#"><code>PropertyDescriptor</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc_nspace :jast java::lang.java.ast %}{% jdoc jast::ASTTypeDeclaration %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-java/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/java/ast/ASTTypeDeclaration.html#"><code>ASTTypeDeclaration</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc_nspace :jast java::lang.java.ast %}{% jdoc_package :jast %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-java/7.4.0-SNAPSHOT/net/sourceforge/pmd/lang/java/ast/package-summary.html#"><code>net.sourceforge.pmd.lang.java.ast</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc_nspace :PrD core::properties.PropertyDescriptor %}{% jdoc !ac!:PrD#uiOrder() %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.4.0-SNAPSHOT/net/sourceforge/pmd/properties/PropertyDescriptor.html#uiOrder()"><code>PropertyDescriptor#uiOrder()</code></a></td>
</tr>
<tr>
<td style="text-align: left"><code class="language-plaintext highlighter-rouge">{% jdoc_old core::Rule %}</code></td>
<td style="text-align: left"><a href="https://docs.pmd-code.org/apidocs/pmd-core/7.3.0/net/sourceforge/pmd/Rule.html#"><code>Rule</code></a></td>
</tr>
</tbody>
</table>
<p>For the javadoc tags, the standard PMD maven modules are already defined as namespaces, e.g. <code class="language-plaintext highlighter-rouge">core</code>, <code class="language-plaintext highlighter-rouge">java</code>, <code class="language-plaintext highlighter-rouge">apex</code>, ….</p>
<p>For the implementation of these tags, see the <a href="https://github.com/pmd/pmd/tree/master/docs/_plugins">_plugins</a> folder.</p>
<h2 id="building">Building</h2>
<p>There are two ways, to execute jekyll:</p>
<ol>
<li>
<p>Using <a href="http://bundler.io/">bundler</a>. This will install all the needed ruby packages locally and execute jekyll:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code># this is required only once, to download and install the dependencies
bundle install
# this builds the documentation under _site
bundle exec jekyll build
# this runs a local webserver as http://localhost:4005
bundle exec jekyll serve
</code></pre></div> </div>
</li>
<li>
<p>Using <a href="https://www.docker.com/">docker</a>. This will create a local docker image, into which all needed ruby
packages and jekyll is installed.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code># this is required only once to create a local docker image named "pmd-doc"
docker build --no-cache -t pmd-doc .
# this builds the documentation under _site
docker run --rm=true -v "$PWD:/src" pmd-doc build -H 0.0.0.0
# this runs a local webserver as http://localhost:4005
docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
</code></pre></div> </div>
</li>
</ol>
<p>The built site is stored locally in the (git ignored) directory <code class="language-plaintext highlighter-rouge">_site</code>. You can
point your browser to <code class="language-plaintext highlighter-rouge">_site/index.html</code> to see the pmd documentation.</p>
<p>Alternatively, you can start the local webserver, that will serve the documentation.
Just go to http://localhost:4005.
If a page is modified, the documentation will automatically be rendered again and
all you need to do, is refreshing the page in your browser.</p>
<p>See also the script <a href="https://gist.github.com/oowekyala/ee6f8801138861072c59ce683bdf737b">pmd-jekyll.sh</a>.
It starts the jekyll server in the background and doesn’t block the current shell.</p>
<h2 id="the-sidebar">The sidebar</h2>
<p>The sidebar is stored as a YAML document under <code class="language-plaintext highlighter-rouge">_data/sidebars/pmd_sidebar.yml</code>.</p>
<p>Make sure to add an entry there, whenever you create a new page.</p>
<h2 id="the-frontmatter">The frontmatter</h2>
<p>Each page in jekyll begins with a YAML section at the beginning. This section
is separated by 3 dashes (<code class="language-plaintext highlighter-rouge">---</code>). Example:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>---
title: Writing Documentation
last_update: August 2017
permalink: pmd_devdocs_writing_documentation.html
---
Some Text
# Some header
</code></pre></div></div>
<p>There are a couple of possible fields. Most important and always
required are <strong>title</strong> and <strong>permalink</strong>.</p>
<p>By default, a page <strong>toc</strong> (table of contents) is automatically generated.
You can prevent this with “toc: false”.</p>
<p>You can add <strong>keywords</strong>, that will be used for the on-site search: “keywords: documentation, jekyll, markdown”</p>
<p>It’s useful to maintain a <strong>last_update</strong> field. This will be added at the bottom of the
page.</p>
<p>A <strong>summary</strong> can also be provided. It will be added in a box before the content.</p>
<p>For a more exhaustive list, see <a href="http://idratherbewriting.com/documentation-theme-jekyll/mydoc_pages.html#frontmatter">Pages - Frontmatter</a>.</p>
<h2 id="alerts-and-callouts">Alerts and Callouts</h2>
<p>See <a href="http://idratherbewriting.com/documentation-theme-jekyll/mydoc_alerts.html">Alerts</a>.</p>
<p>For example, a info-box can be created like this:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{% include note.html content="This is a note." %}
</code></pre></div></div>
<p>It renders as:</p>
<div class="alert alert-info" role="alert"><i class="fas fa-info-circle"></i> <b>Note:</b> This is a note.</div>
<p>Other available types are:</p>
<ul>
<li>note.html</li>
<li>tip.html</li>
<li>warning.html</li>
<li>important.html</li>
</ul>
<p>A callout is created like this:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{% include callout.html content="This is a callout of type default.&lt;br/&gt;&lt;br/&gt;There are the following types available: danger, default, primary, success, info, and warning." type="default" %}
</code></pre></div></div>
<p>It renders as:</p>
<div class="bs-callout bs-callout-default">This is a callout of type default.<br /><br />There are the following types available: danger, default, primary, success, info, and warning.</div>
<h2 id="code-samples-with-syntax-highlighting">Code samples with syntax highlighting</h2>
<p>This is as easy as:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>``` java
public class Foo {
public void bar() { System.out.println("x"); }
}
```
</code></pre></div></div>
<p>This looks as follows:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Foo</span> <span class="o">{</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">bar</span><span class="o">()</span> <span class="o">{</span> <span class="nc">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"x"</span><span class="o">);</span> <span class="o">}</span>
<span class="o">}</span>
</code></pre></div></div>
<h2 id="checking-for-dead-links">Checking for dead links</h2>
<p><code class="language-plaintext highlighter-rouge">mvn verify -pl pmd-doc</code>. This only checks links within the site. HTTP links can be checked
by specifying <code class="language-plaintext highlighter-rouge">-Dpmd.doc.checkExternalLinks=true</code> on the command line.</p>
<div class="tags">
<b>Tags: </b>
<a href="tag_devdocs.html" class="btn btn-outline-secondary navbar-btn cursorNorm" role="button">devdocs</a>
</div>
</div>
<footer>
<hr />
<div>
This documentation is written in markdown. <br />
If there is something missing or can be improved, edit this page on
github and create a PR:
<a
target="_blank"
href="https://github.com/pmd/pmd/blob/master/docs/pages/pmd/devdocs/writing_documentation.md"
role="button"
><i class="fab fa-github fa-lg"></i> Edit on GitHub</a
>
</div>
<hr />
<div class="row">
<div class="col-lg-12 footer">
&copy;2024 PMD Open Source Project. All rights
reserved. <br />
Site last generated: Jul 23, 2024 <br />
<p>
<img src="images/logo/pmd-logo-70px.png" alt="PMD
logo"/>
</p>
</div>
</div>
</footer>
</div>
<!-- /.row -->
</div>
<!-- /.container -->
</div>
<!-- Sticky TOC column -->
<div class="toc-col">
<div id="toc"></div>
</div>
<!-- /.toc-container-wrapper -->
</div>
</div>
<script type="application/javascript" src="assets/jquery-3.5.1/jquery-3.5.1.min.js"></script>
<script type="application/javascript" src="assets/anchorjs-4.2.2/anchor.min.js"></script>
<script type="application/javascript" src="assets/navgoco-0.2.1/src/jquery.navgoco.min.js"></script>
<script type="application/javascript" src="assets/bootstrap-4.5.2-dist/js/bootstrap.bundle.min.js"></script>
<script type="application/javascript" src="assets/Simple-Jekyll-Search-1.0.8/dest/jekyll-search.js"></script>
<script type="application/javascript" src="assets/jekyll-table-of-contents/toc.js"></script>
<script type="application/javascript" src="js/tabstate.js"></script>
<script type="application/javascript" src="js/customscripts.js"></script>
</body>
</html>
View Git Blame Copy Permalink