More documentation about hooks

[kontrollanten]

It'd be good with more details regarding when different hooks are triggered and which arguments are sent to the callback. Below is my proposed assumptions, correct me if I'm wrong. If I'm correct and it's welcome I'll create a PR to extend the documentation.

action:api.video.updated

Triggered when a video is updated via the REST API (i.e. transcoding doesn't count as an update). The callback is called with a VideoModel describing current and previous data.

{
   video: {
     dataValues: VideoModel,
     _previousDataValues: VideoModel,
     _changed: Object, // Describing which properties that changed.
     _modelOptions: {},
     _options: {},
     isNewRecord: bool,
     Thumbnails: [ [ThumbnailModel], [ThumbnailModel] ],
     VideoChannel: VideoChannelModel {
       dataValues: [Object],
       _previousDataValues: [Object],
       _changed: {},
       _modelOptions: [Object],
       _options: [Object],
       isNewRecord: false,
       Actor: [ActorModel],
       Account: [AccountModel]
     },
     VideoFiles: [ [VideoFileModel] ]
   }
 }

action:api.video.uploaded

Triggered when a upload is completed. It doesn't get triggered upon imports.

{
   video: {
     dataValues: VideoModel,
     _previousDataValues: VideoModel,
     _changed: Object, // Describing which properties that changed.
     _modelOptions: {},
     _options: {},
     isNewRecord: bool,
     Thumbnails: [ [ThumbnailModel], [ThumbnailModel] ],
     VideoChannel: VideoChannelModel {
       dataValues: [Object],
       _previousDataValues: [Object],
       _changed: {},
       _modelOptions: [Object],
       _options: [Object],
       isNewRecord: false,
       Actor: [ActorModel],
       Account: [AccountModel]
     },
     VideoFiles: [ [VideoFileModel] ]
   }
 }

[rigelk]

@kontrollanten yes, it would be nice to have that as part of the documentation. However it means being able to pull from the code to generate it automatically, à la OpenAPI like we do for the API documentation. Otherwise it would quickly become out of date/become an extra maintainance burden.

[kontrollanten]

It sounds sound. How is that generated? I guess some annotation should be added in the source code?

[rigelk]

@kontrollanten I don't know of any library that does that yet, unfortunately.

[kontrollanten]

Ah, I thought that you already used a library for that. I've used ESDoc before which I think is okay. The documentation is done with annotations connected to the code. I can do a PR with ESDoc and you'll see how it works.

Edit: I found that ESDoc haven't been updated for 3 years. So I guess JSDoc is a better option.

[rigelk]

@kontrollanten just so you know, we don't have time to dedicate to this right now (next year certainly!), but if you are willing to go for a small POC with either library (or maybe TypeDoc? they claim to be able to generate html or json, which would be easier for integration in existing docs 🤔) and can integrate the generated doc in our existing documentation, why not 🙂