Customised Documentation Schema

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