[Natural Docs Style guide] #documentation #js #javascript #php

natural-docs-style-guide.md

Natural Docs style guide

Comment format for the best output.

The goal is to make the code self-documenting where possible:

• use readable variable, function and class names
• use descriptive URLs
• give the documentation engine the right cues for good output

PHP

Additionally:

• use parameter and return types to show what is expected, and to improve feedback from the linter and PHPUnit / WP Unit

PHPCS configuration

Add the following excludes to phpcs.xml:

<exclude name="Squiz.Commenting.FileComment.MissingPackageTag"/>
<exclude name="Squiz.Commenting.FunctionComment.MissingParamTag"/>

This mutes errors for the following:

• Missing @file (changed to File:)
• Missing @param (changed to Parameters:)

Comment syntax

See x-natural-docs-style-guide-1.php, below.

x-natural-docs-style-guide-1.php

<?php
/**
 * File: src/MyClass1.php
 *
 * This is the primary description, it also appears in the summary pane tooltip, and terminates in a full stop.
 *
 * Note:
 * - The File keyword is redundant as the Files tab automatically
 *   displays all processed files.
 * - However using the full file path here
 *   does help differentiate between files with the same name within Sublime.
 */

// Displays an error if the actual return type
// does not match the expected return type,
// to aid debugging.
declare( strict_types = 1 );

if ( ! class_exists( 'MyClass1' ) ) {

	/**
	 * Class: MyClass1
	 *
	 * This is the primary description, it also appears in the summary pane tooltip, and terminates in a full stop.
	 *
	 * Note:
	 * - This is some further explanation, which terminates in a full stop.
	 * - Classes also appear under the Classes tab, but in that case the file information is hidden.
	 *
	 * Uses:
	 * - ../../../../wp-includes/shortcodes.php
	 */
	class MyClass1 {

		/**
		 * Group: Groups keep things tidy
		 *
		 * This is the primary description, it also appears in the summary pane tooltip, and terminates in a full stop.
		 *
		 * Note:
		 * - This is some further explanation, which terminates in a full stop.
		 * _____________________________________
		 */

		/**
		 * Method: my_function_1
		 *
		 * This is the primary description, it also appears in the summary pane tooltip, and terminates in a full stop.
		 *
		 * Note:
		 * - This is some further explanation, which terminates in a full stop.
		 * - Bullets are more compact, as they don't require separating lines.
		 *
		 * Parameters:
		 *   $my_param_1 - My parameter
		 *   $my_param_2 - Another parameter
		 *   $my_param_3 - This description is required
		 *   $my_param_4 - Otherwise the type won't be shown
		 *
		 * Returns:
		 *   A description of what is returned. Note that The PHP 7 return type declaration is ignored, but the generated code snippet does display it.
		 *
		 * Example:
		 * --- text
		 * // this is a generic code sample
		 * $my_example_1 = 'bar';
		 * ---
		 * --- php
		 * // this is a PHP code sample
		 * $my_example_2 = 'bar';
		 * ---
		 * --- js
		 * // this is a JavaScript code sample
		 * const myExample3 = 'bar';
		 * ---
		 *
		 * See:
		 * - <A URL: Make it descriptive!: http://site.com/page#anchor>
		 * - <Another URL: http://site.com/page2#anchor>
		 *
		 * TODO:
		 * - Fix issue with something #61
		 *
		 * Since:
		 *   1.2.3 - Added
		 *   4.5.6 - Fixed something so it works as expected
		 */
		public function my_function_1( string $my_param_1, array $my_param_2, int $my_param_3, bool $my_param_4 ) : string {
			$my_return = 'test1';
			return $my_return;
		}
	}
}