discussion: introspect services for pre and post hooks, and other routes

[hdngr]

1. Should we automate documentation of pre and post hooks? All hooks, or just often used hooks

2. Should we introspect services (or even the underlying app) for routes not defined in the service itself?

   # For example
   app.use('/users', service);
   app.service('users')
   .hooks(hooks);
   app.post('/users/password', handlePasswordReset);

   @daffl - https://feathersjs.slack.com/archives/C52QSFK0A/p1507333034000102

I think the conversation is worth having. Maybe we decide that automation/automated introspection is not the answer, and maybe just more robust documentation on the best way to use swagger to document hook like functionality.

Thanks for all of the great work!!

[daffl]

I like the idea you mentioned on Slack of parsing JSDoc style comments to generate the documentation. Some questions to investigate are:

• Built in services should probably bring their own default documentation but how do you customize it? Usually you don't create a new class so how does JSDoc fit in?
• Going through the hooks and grabbing the documentation (in the order they are executed) is also a great idea the question is, is there a way to do this automatically? Manually would be fairly easy by parsing __dirname in each file and adding it to the exported function as a .docs property or something like that.

[hdngr]

• Built in services could use some sort of "shim" class. Like a default class Doc class that would create the basics based on methods that were implemented find create etc... If the service used the class then it would be class Doc extends SomeService and then only document the service. For feathers-mongoose routes, it would generate everything, but for something like feathers-authentication it would be create. Then the user would have the ability to create there own - class CustomDoc or class CustomDoc extends Doc.
• I think to have value it would have to have some sort of automation. Even if it just logged the hooks by there name it could be valuable. e.g. before 'auth create': 'jwt', 'local'. Again, if the user wanted to add more detail on the hooks and what they are doing (especially for custom functions) they could do that.

[hdngr]

I would think that at the least, we would introspect for the following:

• Service methods - create, patch, update, delete, etc., not a whole lot different than how you do already
• .hooks
• .filter

Other considerations?

• any custom events
• custom methods?
  • I have a users service with a password reset method POST /users/reset-password

One use case:

A package like feathers-mongoose is used for a messages service. feathers-mongoose could include es doc of the primary methods. All that would be left would be for the user's hooks, and filters to be documented. e.g. before create, restrict to owner, id field: '_id', owner field: 'from'

What other thoughts?

[hdngr]

@daffl did a little bit of research here... introspecting hooks could work. Changing one of the feathers conventions to have hooks return named functions as would be one way - e.g.

function someAwesomeHook () {
     return function() {...}
}

Would become

function someAwesomeHook () {
     return function someAwesomeNameForDocs(hook) {...}
}

This is may not be intuitive/obvious.

Another approach would be to wrap the hook

app.service('coolService').hooks({
  before: app.providers.esdoc(auth.hooks.authenticate('jwt'))
})

With this approach, maybe the common hooks give obvious documentation signals.

[daffl]

Custom hooks could still export their own docs I think. Something like

const document = require('feathers-api-doc');

/**
 * A hook method
 */
module.exports = function hookMethod(method) {

}

module.exports.docs = document(__dirname);

Basically anything that has a .docs property (services etc.) can be used by Swagger.

[hdngr]

totally - and what is the purpose of passing __dirname? What are we looking for in the module/service's directory?

[daffl]

Oops, that should've been __filename to parse the documentation from our file and export it with the function.

[hdngr]

oh - got it. So, document would need to be smart enough to know what was going on in every file where document(__dirname)? Hooks, filters, on (events), etc? Or, would it be configured?

[Mairu]

Any custom generation of docs should by handled by independet packages. The scope of this package is more to consume the docs.