Ben Goldsworthy
e8d6dbe13d
* Adapt after the 2.5.9d1 accident. * Corrections to changelog. * Also added @revision and @timestamp PHPDOC tags @revision and @timestamp used for SVN refs. Full enumeration of added custom PHPDOC tags: @accountable, @bib, @biblio, @callback, @commit, @committer, @contributor, @courtesy, @date, @datetime, @lastmodified, @modified, @publisher, @reporter, @revision, @timestamp, @user.Some tags like @reporter and @contributor are more used than others. * Readme header upgrade. * Create deploy-to-wordpress.org.yml * Add distignore * Comment out `build` command, replace npm with composer * Remove placeholder comments * Add build commands * Fix typo * Fix version number bug * Make zip without top-level directory * Append tag name to plugin zip * Clean up a bit * Rename workflow config * Fix upload paths * Append tag name to artifact * Fix paths * Revert path fix * Try again * Add wplm-config.xml to buildfiles * Fix indentation * Rename development/csscat.sh to css/csscat.sh * Rename development/customized-documentation-schema.txt to customized-documentation-schema.txt * Rename development/customized-template-stack.txt to customized-template-stack.txt * Version number related fixes before pull request. * Move csscat script to tools dir * Rename csscat * Refactor script * Update customized-documentation-schema.txt * Replace empty lines in help output * Escape empty lines. * Delete 3 items from `.distignore` As mentioned, CONTRIBUTING.md and README.md should be included in distributions. - As an invitation to the Community. - As a tangible proof of goodwill after the 2.5.9d1 accident. Also SECURITY.md so Footnotes users see that we’re concerned, and can reach out without transiting via GitHub. * Include CONTRIBUTING.md README.md SECURITY.md * Update sync w/ 5.7 tested. * Update * Update composerfiles Co-authored-by: pewgeuges <73141620+pewgeuges@users.noreply.github.com>
280 lines
5.2 KiB
Plaintext
280 lines
5.2 KiB
Plaintext
customized-documentation-schema.txt
|
|
@lastmodified 2021-03-05T0501+0100
|
|
|
|
|
|
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
|
|
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
|
|
2021-01-24T2310+0100
|
|
2021-02-08T0415+0100
|
|
|
|
▲ 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
|