D 2018-07-04T13:53:59.126
L Rationale
N text/x-markdown
P 16fae529a679fca600ff4d7b426e68b25c10449ee1e0836efb80e78dcc83518b
U mario
W 7642
## Purpose

Plugin meta data is intended for basic code extension schemes.

  *  Primary target are scripting languages.

  *  Where "plugins" can be contained within a single source file.

  *  It's just about the meta comment format however. There's no inherent
     definition on how to tie application-level callback / hook / class APIs.

  *  Maintenance is simplified by having technical and description
     attributes *embedded*.

  *  Foremost it's very discoverable and useful to end-users.

  *  Extensibility is a core feature. (This spec is just to define
     some obvious standard fields.)

  *  And while that's not a goal, even can help with application packaging.


## Design Rationale

To make this suitable across programming languages, the syntax needed to
be generic and not be tied to specific docblock variants.

  *  Hence a consecutive `#` block is recommended as default comment style.

       *  Individual implementations are encouraged to support any alternative
           comment block syntaxes.

  *  `key: value` fields are a rather obvious choice. And they're already
     used in related specs (PKG-INFO, Debian control, etc.)


  *  Key names should be single `words:`, or RFC `message-header:` combinations
     at most.

       *  They should never contain spaces, as that made it really cumbersome
           to parse/process. (→ And that's how you get ants!)

       *  In some languages it's a rather unfortunate idiom to use "ASCII art"-style
           comments. Often there's all sorts of personal variations like
           "Written by:" or "Authored by:" and so on - due to lack of standardization
           and language ecosystem.

       *  Which is precisely what the PMD spec is meant to help against.

  *  All basic fields are suitable to CLI tools, as well as GUI applications, or
     web apps.

       *  Additions like `icon:` etc. can be used for more specific cases.

  *  `type:` is one recommended way to support the more widespread "hook" or
     service locator systems.

       *  Albeit even `category:` or custom fields can be fitted for more complex needs.

  *  Utilizing PMD does not require *each and every* source script to carry a meta data
     block.

       *  Obviously it's only meant to augment those code bits that represent
           features or extensions.

       *  Though, of course; once you start classifying scripts, or have a huge
           enough codebase - plugin meta data will appear even in core files.
           (And I'd usually tag them as such - `type: core`)

  *  "Modules" are not scope of this spec.

       *  Of course, for "module packages", one could elect a primary/invocation
           script, add plugin meta data only there, and leave the rest undocumented.

  *  Another essential feature of PMD is a common [config:](wiki/config) scheme.

       *  Many times plugins themselves represent just settings/adaptions.

       *  For more complex code it's very common to introduce new global application
           settings.

       *  Rather than leave each plugin to also micromanage an UI for settings those,
           defining a standard way to collect options (globally or on per-plugin basis)
           is a neat gimmick.

  * There's quite some overlap. But PMD has an entirely different scope than build/source-packaging tools (npm, pip, composer, etc).

       * The plugin spec is meant for runtime configuration between individual scripts, not a global project recipie.

       * With e.g. [depends](wiki/depends) being more of a recommendation than leading to dependency hell.

       * Its scope is end-user discoverable documetation rather than build systems.

       * Although one could generate/augment e.g. package.json from a list of `# depends: npm:xyz, npm:abc, …`


## Inspired by

Both syntax and usage didn't come out of thin air. There's lots of prior art
and things PMD tries to be compatible with to some extend:

  *  Standard field names mostly come from the [Debian packaging spec](https://www.debian.org/doc/debian-policy/#document-ch-controlfields).
     Which is sort of a standard already. (No need for NIH field names.)

  *  One of the few things Wordpress got right (almost). They've been using
     (or rather inherited) a similar comment-based plugin description scheme.

      *  Except for the abhorrent spaced key names, and not knowing what else to do with it.
      *  Most WP plugins have to define config hooks/settings/handling themselves
          to this day.

  *  There's a few similar language-specific meta data schemes:

      *  JS userscripts use a constrained docblock-style scheme for similar purposes.

      *  TCL, teapot?
 
      *  ...  (readd from old list...)


## Why not?

Before PMD came to be, I've also tried a couple of common mishaps:

**Meta-data in code**:

  *  Most intial extensions/plugin schemes (e.g. PHP4-era code) use
     class constants, properties, or function hooks to register with
     the application API.

  *  However such meta info code is just used in a one-off fashion.
     Either once for installation, or rarely for option configuration.
     It still might show up in menus, but otherwise is pretty much dead code.

**External .meta/.ini/.xml files**

  *  For binary apps / compiled languages, having a module description scheme
     externalized is often unavoidable.

  *  But auxilliary meta files often just add complexity (copy and updating them
     along the real code), not features per se.

  *  It's harder to eschew for broader "module" schemes. But for the purpose of slim
     feature hooks, embeding meta infos turns out most practicable.


### DocBlock considered harmful

Most scripting languages use some form of DocBlock, PerlDoc variants, decorators
or any custom API documentation scheme. They're quite essential or even existential 
or function/class-level description.

Not so much for file-level docblocks however. Those decorations rarely add anything
worthwhile to autogenerated docs. Which would have been a great reason to repurpose
DocBlocks for PMD with an established syntax, but:

  *  Most DocBlock parsers trip over custom attributes. A few would just yield a bunch
     of warnings. But generally there's no support for anything but textual descriptions.

  *  The well is poisoned with boilerplate. Due to being this widely adopted, IDEs
     started adding boilerplate DocBlocks. Which contributed to its diminished usefulness.

  *  Variations across languages (PerlDoc vs JavaDoc) also would have made DocBlock
     look out of place as default syntax for plugin meta data.

Another dealbreaker was the excessive pairing with...


### The great license plague of the 90s

License blobs in lieu of proper file-level documentation.

  *  Now to be fair, most academic/attribution licenses recommend them to be embeded
     with source code. (None require this to be at the file start though.)

  *  For reciprocal licenses, which do not apply on a file-by-file basis to being with,
     this is entirely unfounded. Nonetheless it became a toxic habit to plaster source
     code with license excerpts - oftentimes to avoid effort on actual code descriptions.

  *  It's an abomination of the purpose of code comments.

PMD mandates to be in the first comment block in order to combat exactly this. The
intend behind the [license](wiki/license) standard field is to legitimize SPDX identifiers
instead.



Z 050aa77b8d6298f19ebe4e1893321a7b