diff --git a/Customised-Documentation-Schema.textile b/Customised-Documentation-Schema.textile new file mode 100644 index 0000000..51c39bb --- /dev/null +++ b/Customised-Documentation-Schema.textile @@ -0,0 +1,276 @@ +customized-documentation-schema.txt + + +Plugin Footnotes for WordPress, v2.5.4 and later + + +Customized documentation schema +‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ + +In community-based, open source projects, it is important to comprehensively +recognize, acknowledge and document how developers, testers and users helped +build the product. +https://wordpress.org/support/topic/great-tool-1549/#post-14039334 + +Note: Per the WordPress Coding Standards, the '@author' tag must not be used. +https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/ + +PHPDOC tag: Role: Acknowledgment in the changelog: +‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ +@contributor Provided code. “thanks to @USERNAME code contribution.” +@contributor Provided design. “thanks to @USERNAME design contribution.” +@contributor Provided content. “thanks to @USERNAME design contribution.” (!) + +@reporter Reported a bug. “thanks to @USERNAME bug report.” +@reporter Reported an issue. “thanks to @USERNAME issue report.” +@reporter Requested a feature. “thanks to @USERNAME issue report.” (!) +@reporter Provided feedback. “thanks to @USERNAME feedback.” +@reporter Provided an example. “thanks to @USERNAME example provision.” + +@user Allowed insight. “thanks to @USERNAME usage.” + +@accountable Edited the codebase. - + +@committer Uploaded a version. - + + +PHPDOC tags & custom tags +‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ + +▲ Source for standard tags: +https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html + +@access +@author +@copyright +@deprecated +@example +@ignore +@internal +@link +@see +@since +@tutorial +@version +inline {@internal}} +inline {@inheritdoc} +inline {@link} + +Sidepane: + +phpDocumentor tags + @abstract + @access + @author + @category + @copyright + @deprecated + @example + @final + @filesource + @global + @ignore + @internal + @license + @link + @method + @name + @package + @param + @property + @return + @see + @since + @static + @staticvar + @subpackage + @todo + @tutorial + @uses + @var + @version + +phpDocumentor Inline tags + inline {@example} + inline {@id} + inline {@internal}} + inline {@inheritdoc} + inline {@link} + inline {@source} + inline {@toc} + inline {@tutorial} + + +▲ Tags required/recommended by WordPress coding standard: +https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/ + +Note: The only tag added from draft PSR-5 recommendations is @type. +https://stackoverflow.com/questions/48202550/source-of-type-tag-in-docblock + +@access +@author [DO NOT USE] +@copyright +@deprecated +@global +@ignore +@internal +@license +@link +@method +@package +@param +@return +@see +@since +@static +@staticvar +@subpackage +@todo +@type +@uses +@var + + +▲ Tags added by PHPStan: +https://phpstan.org/blog/generics-in-php-using-phpdocs + +@extends +@implements +@template + + +▲ Tags supported in Atom TextMate found in VS Code 1.47.3: +/usr/share/code/resources/app/extensions/php/syntaxes/php.tmLanguage.json +Note the 4 tags appended to the list, hence initially missing. + +@api +@abstract +@author +@category +@copyright +@example +@global +@inherit[Dd]oc +@internal +@license +@link +@method +@property(-(read|write))? +@package +@param +@return +@see +@since +@source +@static +@subpackage +@throws +@todo +@var +@version +@uses +@deprecated +@final +@ignore + +MISSING TAGS: + +- wrt phpDocumentor: +@access +@filesource +@id +@name +@staticvar +@toc +@tutorial +@usedby + +- wrt WordPress: +@type + +- wrt PHPStan: +@extends +@implements +@template + + +▲ up-to-date list (standard/WP/PHPStan, custom): + +@api +@abstract +@access +@author +@category +@copyright +@deprecated +@example +@extends +@filesource +@final +@global +@id +@ignore +@implements +@inherit[Dd]oc +@internal +@license +@link +@method +@name +@package +@param +@property(-(read|write))? +@return +@see +@since +@source +@static +@staticvar +@subpackage +@template +@throws +@toc +@todo +@tutorial +@type +@usedby +@uses +@var +@version + +@accountable +@bib +@biblio +@callback +@commit +@committer +@contributor +@courtesy +@date +@datetime +@lastmodified +@modified +@publisher +@reporter +@revision +@timestamp +@user + + +▲ Config (original, missing and added tags), example of VS Code. +/usr/share/code/resources/app/extensions/php/syntaxes/php.tmLanguage.json + +original: +abstract|api|author|category|copyright|deprecated|example|final|global|ignore|inherit[Dd]oc|internal|license|link|method|package|param|property(-(read|write))?|return|see|since|source|static|subpackage|throws|todo|uses|var|version + +missing: +|access|filesource|id|name|staticvar|toc|tutorial|usedby + +WordPress: +|type + +PHPStan: +|extends|implements|template + +custom: +|accountable|bib|biblio|callback|commit|committer|contributor|courtesy|date|datetime|lastmodified|modified|publisher|reporter|revision|timestamp|user \ No newline at end of file