documentation-schema.txt


A.N.R.GHG Publishing Helper plugin for WordPress

@since 0.9.0
@since 0.24.6 Current version.


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

Consistently, contributors and reporters are given credit, no matter if they
contributed code to—or reported for—the project at stake, or other projects.
That brings the need to disambiguate `@contributor` and `@reporter` tags, by
appending an asterisk if a contribution to another project is reused in this
project, and the other project is acknowledged for any code that was already
in there, and is reused here, or two asterisks for reports and contributions
to another project, known due to contributing to the other project.

Examples: @contributor** @userid;  @reporter** @userid;  @courtesy** @userid

Note: Per the WordPress Coding Standards, the `@author` tag must not be used.

https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/

For other acknowledgments, in particular if an author’s WordPress User ID is 
unknown, `@courtesy` is used.


PHPDOC tag:      Role:                 Acknowledgment in the changelog:
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
@contributor     Provided code.        “thanks to @USERID code contribution.”
@contributor     Provided design.      “thanks to @USERID design contribution.”
@contributor     Provided content.     “thanks to @USERID design contribution.”

@reporter        Reported a bug.       “thanks to @USERID bug report.”
@reporter        Reported an issue.    “thanks to @USERID issue report.”
@reporter        Requested a feature.  “thanks to @USERID issue report.” (!)
@reporter        Provided feedback.    “thanks to @USERID feedback.”
@reporter        Provided an example.  “thanks to @USERID example provision.”

@user            Allowed insight.      “thanks to @USERID use case.”

@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/prohibited 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 [PROHIBITED]
@copyright
@deprecated
@global
@ignore
@internal
@license
@link
@method
@package
@param
@return
@see
@since
@static
@staticvar
@subpackage
@todo
@type
@uses
@var


▲ Tag used in WordPress theme docblocks:

@hooked


▲ 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


▲ List up-to-date for the project this file is included in:

- standard/WP/PHPStan:

@api
@abstract
@access
@author
@category
@copyright
@deprecated
@example
@extends
@filesource
@final
@global
@hooked
@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

- custom:

@accountable
@bib
@biblio
@callback
@commit
@committer
@contributor
@courtesy
@date
@datetime
@done
@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|hooked

PHPStan:
|extends|implements|template

custom:
|accountable|bib|biblio|callback|commit|committer|contributor|courtesy|date|datetime|done|lastmodified|modified|publisher|reporter|revision|timestamp|user