Plugins Must Declare Annotations [WIP]

[markwpearce]

Addresses #1348

Plugins must declare their annotations, so that can be validated.

• Add Documentation about Annotations
• Fix Deprecated docs with references to old plugin events
• Agree on format of annotation declarations
• Etc

[markwpearce]

@TwitchBronBron

The docs I added follow along with the description from the issue, but I'm thinking it may be easier to deal with annotations that are provided as Types?

eg:

const myAnnotation = new TypedFunctionType()
myAnnotation.name = 'MyAnnotation';
myAnnotation.params = [
    {name: 'id', type: StringType.instance},
    {name: 'extraData', type: new AssociativeArrayType(), optional: true}
];

this.annotations = [myAnnotation]

(perhaps we could update the constructor or create a helper function to create it all at once?)

This would mean we wouldn't have to parse the declaration, but instead use it directly... and wouldn't need to have extra error handling on bad parsed values, etc.

[luis-soares-sky]

Mostly off-topic feedback 👼

[luis-soares-sky]

The remaining API methods are all named with a specific order of "time" > "subject" > "action", i.e. beforeProgramCreate, afterFileValidate, etc. But these either disregard the "subject" entirely, or have their "subject" and "action" reversed.

Also, not sure I understand the difference between the program's serialize and build steps, and the need for the beforePrepublish and afterPrepublish steps. Is there a need for all of these?

- `afterProgramCreate`
    - (...)
    - `afterProgramValidate`
- `beforeProgramPublish`
    - For each file:
        - `beforeFilePrepare`
        - `afterFilePrepare`
- `afterProgramPublish`
- `beforeProgramDispose`

[markwpearce]

I agree the naming should be more consistent.

@TwitchBronBron can we make this change?
also, maybe you could add a little more to these docs to explain what these events represent?

[TwitchBronBron]

Yeah, I'm definitely open to tweaking some of these names so they're more consistent.

With regard to the prepublish, serialize, build steps, they each have their own purpose, but we should definitely add more documentation around them to better explain their differences.

[luis-soares-sky]

Same as above:

- `beforeFileProvide`
- `afterFileProvide`

[TwitchBronBron]

Here, file isn't the subject—we're asking plugins to provide a file, not the files to provide something. So the term subject is a bit different, though I can see it being read slightly that way.

But perhaps it doesn't matter, and we should just align on the naming convention anyway?