Plugin meta data

Plugin meta data is a comment scheme for scripting languages. It's meant for application-level feature and config management. And typically looks like this:

# encoding: utf-8
# api: appname
# title: My Plugin
# description: Lists all the things
# type: feature
# version: 1.0
# state: stable
# category: ui
# license: MITL
# config: { name: myconf, value: 1, type: boolean, description: enable foo }
# And here goes a longer doc/comment.

Most field: names are fairly standard. Some fields are classifiers or hooks for the application API. Others are mostly descriptions for end users.
PMD is meant to be rather obvious, easy to extract, and reusable across languages.

Common fields

key usage
api Application identifier
type Primary plugin "hook" or general classifier
title Title
description Summary or description of plugin
category UI classification / menu hook
version Script-specific version
state stable/beta/etc
license license identifier
author author or contributor list
config List of config options (JSOL struct)

Custom properties are encouraged for further project or tool requirements.

Comment syntax

The preferred comment scheme is a cohesive # hash block - because that's supported with most scripting languages (and aligns best with an optional shebang).

  • Implementations may support multi line /* … */, //, <# … #> comment blocks.

  • It's however important that this meta block is the topmost comment in a script. (See Rationale)

  • All # key: value entries occupy consecutive comment lines with coherent formatting.

  • Key names should be interpreted case-insensitively. Rfc/message-style, no spaces allowed.

  • Typically they carry just plain strings, because that's easiest to process for trivial regex lexing.

  • Longer field values might be multi-line by indenting wrapped text at least ␣␣ two spaces beyond other key: comment lines.

  • The config field is one of the few structured entries, and often spans multiple lines.

  • Whereas e.g. author or depends are sometimes comma-separated lists. Though the plugin meta extraction might still just read them as strings; and leave list handling for later.

Overall it's a bit like YAML; just in a comment block.

Notably an empty line in the comment section separates plugin meta data from a more detailed description section. Albeit this would often pertain application end users, more than code implementation details or technical minutae.