pmd_devdocs_writing_documentation.html

<!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" href="css/syntax.css">


<link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!--<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">-->
<link rel="stylesheet" href="css/modern-business.css">
<link rel="stylesheet" href="css/lavish-bootstrap.css">
<link rel="stylesheet" href="css/customstyles.css">
<link rel="stylesheet" href="css/theme-blue.css">
<link rel="stylesheet" href="css/pmd-customstyles.css">

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-cookie/1.4.1/jquery.cookie.min.js"></script>
<script src="js/jquery.navgoco.min.js"></script>


<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js"></script>
<script src="js/toc.js"></script>
<script src="js/customscripts.js"></script>

<link rel="shortcut icon" href="images/favicon.ico" type="image/x-icon">
<link rel="icon" href="images/favicon.ico" type="image/x-icon">

<!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
<![endif]-->

<link rel="alternate" type="application/rss+xml" title="" href="https://pmd.github.io/pmd/feed.xml">

    <script>
        $(document).ready(function() {
            // Initialize navgoco with default options
            $("#mysidebar").navgoco({
                caretHtml: '',
                accordion: true,
                openClass: 'active', // open
                save: false, // leave false or nav highlighting doesn't work right
                cookie: {
                    name: 'navgoco',
                    expires: false,
                    path: '/'
                },
                slide: {
                    duration: 400,
                    easing: 'swing'
                }
            });

            $("#collapseAll").click(function(e) {
                e.preventDefault();
                $("#mysidebar").navgoco('toggle', false);
            });

            $("#expandAll").click(function(e) {
                e.preventDefault();
                $("#mysidebar").navgoco('toggle', true);
            });

        });

    </script>
    <script>
        $(function () {
            $('[data-toggle="tooltip"]').tooltip()
        })
    </script>
    <script>
        $(document).ready(function() {
            $("#tg-sb-link").click(function() {
                $("#tg-sb-sidebar").toggle();
                $("#tg-sb-content").toggleClass('col-md-9');
                $("#tg-sb-content").toggleClass('col-md-12');
                $("#tg-sb-icon").toggleClass('fa-toggle-on');
                $("#tg-sb-icon").toggleClass('fa-toggle-off');
            });
        });
    </script>
    

</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-inverse navbar-fixed-top">
    <div class="container topnavlinks">
        <div class="navbar-header">
            <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
            </button>
            <a class="fa fa-home fa-lg navbar-brand" href="index.html">&nbsp;<span class="projectTitle"> PMD Source Code Analyzer Project</span></a>
        </div>
        <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
            <ul class="nav navbar-nav navbar-right">
                <!-- toggle sidebar button -->
                <li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>
                <!-- entries without drop-downs appear here -->
                
                
                <li><a href="https://github.com/pmd/pmd/releases/latest" target="_blank">Download</a></li>
                
                
                <li><a 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.-->
                
                
                <!--comment out this block if you want to hide search-->
                <li>
                    <!--start search-->
                    <div id="search-demo-container">
                        <input type="text" id="search-input" placeholder="search...">
                        <ul id="results-container"></ul>
                    </div>
                    <script src="js/jekyll-search.js" type="text/javascript"></script>
                    <script type="text/javascript">
                            SimpleJekyllSearch.init({
                                searchInput: document.getElementById('search-input'),
                                resultsContainer: document.getElementById('results-container'),
                                dataSource: 'search.json',
                                searchResultTemplate: '<li><a href="{url}" title="Writing documentation">{title}</a></li>',
                    noResultsText: 'No results found.',
                            limit: 10,
                            fuzzy: true,
                    })
                    </script>
                    <!--end search-->
                </li>
            </ul>
        </div>
        </div>
        <!-- /.container -->
</nav>

<!-- Page Content -->
<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 6.22.0</li>
    
    
    <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_next_major_development.html">PMD 7.0.0 development</a></li>
                

                <li><a href="pmd_about_help.html">Getting help</a></li>
                

        </ul>
     </li>
       
        
    <li>
        
        <a href="#">User Documentation</a>
        
        <ul>
            
            
                <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 class="subfolders">
                    <a href="#">Extending PMD</a>
                    <ul>
                        
                        
                        <li><a href="pmd_userdocs_extending_writing_pmd_rules.html">Writing a rule</a></li>
                        
                        
                        <li><a href="pmd_userdocs_extending_writing_xpath_rules.html">Writing XPath 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_metrics_howto.html">Using and defining code metrics</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>
                        
                        
                    </ul>
                </li>
                
                
                <li><a href="pmd_userdocs_cpd.html">Copy-paste detection</a></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_ant.html">Ant</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="#">Ecmascript 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="#">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="#">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_vf.html">Index</a></li>
                        
                        
                        <li><a href="pmd_rules_vf_security.html">Security</a></li>
                        
                        
                    </ul>
                </li>
                
                
                <li class="subfolders">
                    <a href="#">VM Rules</a>
                    <ul>
                        
                        
                        <li><a href="pmd_rules_vm.html">Index</a></li>
                        
                        
                        <li><a href="pmd_rules_vm_bestpractices.html">Best Practices</a></li>
                        
                        
                        <li><a href="pmd_rules_vm_design.html">Design</a></li>
                        
                        
                        <li><a href="pmd_rules_vm_errorprone.html">Error Prone</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_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_jsp.html">JSP Support</a></li>
                

                <li><a href="pmd_java_metrics_index.html">Java code metrics</a></li>
                

                <li><a href="pmd_apex_metrics_index.html">Apex code metrics</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_adding_new_language.html">Adding a new language</a></li>
                        
                        
                        <li><a href="pmd_devdocs_major_adding_new_cpd_language.html">Adding a new CPD language</a></li>
                        
                        
                        <li><a href="pmd_devdocs_major_adding_new_metrics_framework.html">Adding metrics support to a language</a></li>
                        
                        
                    </ul>
                </li>
                
                
                <li class="subfolders">
                    <a href="#">Experimental features</a>
                    <ul>
                        
                        
                        <li><a href="pmd_devdocs_experimental_ast_dump.html">Creating (XML) dump of the AST</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_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 class="subfolders">
                    <a href="#">Project management</a>
                    <ul>
                        
                        
                        <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>
                        
                        
                    </ul>
                </li>
                
                
        </ul>
     </li>
       
        
        <!-- if you aren't using the accordion, uncomment this block:
           <p class="external">
               <a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
           </p>
           -->
</ul>

<!-- this highlights the active parent class in the navgoco sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");</script>

        </div>
        
        
        <!-- Content Column -->
        <div class="col-md-9" id="tg-sb-content">
            <div class="post-header">
   <h1 class="post-title-main">Writing documentation</h1>
</div>


<div class="post-content">

   
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
  // Handler for .ready() called.

$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });

});
</script>

<div id="toc"></div>

    
    <a target="_blank" href="https://github.com/pmd/pmd/blob/master/docs/pages/pmd/devdocs/writing_documentation.md" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>

    
  <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="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="highlighter-rouge">%lang%</code> are located in
<code class="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="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="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="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="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="highlighter-rouge">{% rule "java/codestyle/LinguisticNaming" %}</code></td>
      <td style="text-align: left"><a href="pmd_rules_java_codestyle.html#linguisticnaming"><code class="highlighter-rouge">LinguisticNaming</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc core::Rule %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/Rule.html#"><code class="highlighter-rouge">Rule</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc !q!core::Rule %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/Rule.html#"><code class="highlighter-rouge">net.sourceforge.pmd.Rule</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc core::Rule#setName(java.lang.String) %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/Rule.html#setName(java.lang.String)"><code class="highlighter-rouge">setName</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc !c!core::Rule#setName(java.lang.String) %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/Rule.html#setName(java.lang.String)"><code class="highlighter-rouge">Rule#setName</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc !a!core::Rule#setName(java.lang.String) %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/Rule.html#setName(java.lang.String)"><code class="highlighter-rouge">setName(String)</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc !ac!core::Rule#setName(java.lang.String) %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/Rule.html#setName(java.lang.String)"><code class="highlighter-rouge">Rule#setName(String)</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc core::properties.PropertyDescriptor %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/properties/PropertyDescriptor.html#"><code class="highlighter-rouge">PropertyDescriptor</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc_nspace :jast java::lang.java.ast %}{% jdoc jast::ASTAnyTypeDeclaration %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-java/6.22.0/net/sourceforge/pmd/lang/java/ast/ASTAnyTypeDeclaration.html#"><code class="highlighter-rouge">ASTAnyTypeDeclaration</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc_nspace :jast java::lang.java.ast %}{% jdoc_package :jast %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-java/6.22.0/net/sourceforge/pmd/lang/java/ast/package-summary.html#"><code class="highlighter-rouge">net.sourceforge.pmd.lang.java.ast</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc_nspace :PrD core::properties.PropertyDescriptor %}{% jdoc !ac!:PrD#uiOrder() %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.22.0/net/sourceforge/pmd/properties/PropertyDescriptor.html#uiOrder()"><code class="highlighter-rouge">PropertyDescriptor#uiOrder()</code></a></td>
    </tr>
    <tr>
      <td style="text-align: left"><code class="highlighter-rouge">{% jdoc_old core::Rule %}</code></td>
      <td style="text-align: left"><a href="https://javadoc.io/page/net.sourceforge.pmd/pmd-core/6.21.0/net/sourceforge/pmd/Rule.html#"><code class="highlighter-rouge">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="highlighter-rouge">core</code>, <code class="highlighter-rouge">java</code>, <code class="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="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="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="highlighter-rouge">_site</code>. You can
point your browser to <code class="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="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="highlighter-rouge">---</code>). Example:</p>

<div class="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="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="fa 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="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="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="n">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="highlighter-rouge">mvn verify -pl pmd-doc</code>. This only checks links within the site. HTTP links can be checked
by specifying <code class="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-default navbar-btn cursorNorm" role="button">devdocs</a>
        
        
    </div>


</div>

<hr class="shaded"/>

<footer>
            <div class="row">
                <div class="col-lg-12 footer">
               &copy;2020 PMD Open Source Project. All rights reserved. <br />
 Site last generated: Feb 13, 2020 <br />
<p><img src="images/pmd-logo-small.png" alt="Company logo"/></p>
                </div>
            </div>
</footer>


        </div>
        <!-- /.row -->
    </div>
    <!-- /.container -->
</div>
</div>
</body>

</html>