footnotes/note-for-developers.txt

note-for-developers.txt
@datetime 2020-12-19T0609+0100
@lastmodified 2021-02-12T0616+0100


Plugin Footnotes for WordPress, v2.5.3 and later


A.  Customized template parts
    ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾

Since v2.2.6, Footnotes supports custom templates.

Custom templates may be loaded from a sibling folder 'footnotes-custom'
or since v2.4.0 from a folder 'templates/footnotes/' in the active theme.

Priority order:
    1. active theme
    2. sibling folder
    3. internal

See footnotes/class/template.php:67..116


1. Active theme
   ‾‾‾‾‾‾‾‾‾‾‾‾
Please create a folder 'templates/footnotes/' in your child theme and
store all your public custom templates for Footnotes directly therein.

Existing homonymous templates are loaded instead of their counterparts in
wp-content/plugins/footnotes/templates/public/.


2. Sibling folder
   ‾‾‾‾‾‾‾‾‾‾‾‾‾‾
Please make a sibling of the "footnotes" folder called 'footnotes-custom' and
the same internal structure and file names as 'footnotes/templates/public/'.

Example for custom tooltips:

footnotes-custom
└── templates
    └── public
        ├── footnote.html
        └── tooltip.html

Note: The timing parameters in the inline jQuery script 'tooltip.html' are already
configurable in the dashboard > Referrers and tooltips > Tooltip timing.




B.  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.”

@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 VSCode 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) as per 2021-02-08T0335+0100:

@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
@user


▲ Config (original, missing and added tags):
/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|user