[wp-meta] [Making WordPress.org] #7531: Hook automatic documentation

[Making WordPress.org]

#7531: Hook automatic documentation
------------------------------+--------------------
 Reporter:  coquardcyr        |      Owner:  (none)
     Type:  enhancement       |     Status:  new
 Priority:  normal            |  Milestone:
Component:  Plugin Directory  |   Keywords:
------------------------------+--------------------
 Hey,
 Currently as a developer the experience about searching hooks on an
 installed plugin is a pain.

 First when picking a new plugin on the marketplace nothing indicates to me
 if the plugin makes use of actions or filters to configure it to my needs.
 The only way to know is to download the plugin then open it in my IDE and
 each for each occurrence from the method ''apply_filters'' and
 ''do_action''.

 Then once the plugin is installed and I am using a filter or an action, it
 is not finished if there is an update and I want to make sure the
 developer from the plugin didn't remove or change the plugin. I need to
 jump again into the code and make sure hooks weren't touched.

 My idea to tackle that would be simple.
 On one hand I think this documentation is important for end users but on
 another one I don't want to make plugins developers waste a bunch of more
 time on it.

 That's why automation seems the good way to me as it will allow developers
 to be able to provide that in one command in the cli.

 To reduce the amount of memory that would be used on wordpress.org by that
 feature I would split it into two parts linked with a file as an interface
 between them describing hooks.
 Moreover the choice of a separation between the tools to make an interface
 which leaves room for other tools in the future as an IDE plugin and it
 also gives the opportunity for the developer to change the file generated
 in case there is an issue with the cli command.

 So for that feature we would have a cli command that generates a file
 describing the hooks from the plugins and another part about displaying
 information about hooks on the marketplace from wordpress.org using that
 file.

 For that cli part,I already started something here with my custom
 framework that could be seen as a poc: https://github.com/wp-launchpad
 /hooks-extractor
 However, it is based on regex and it seems like it has a lot of flaws so
 there is still room for improvement.
 For example, I guess another approach based on a tokenizer would work
 better.


 Concerning the generated documentation I got that repository which is not
 really related to the second part: https://github.com/wp-launchpad/hook-
 list

 Nevertheless it generates a small documentation from a yaml file which can
 be useful to display some information to the end user.

 The idea for that second part would be to have a list of hooks and their
 documentation for each plugin when the file is detected. This would also
 promote the usage from hooks through the community as they are not that
 much common.

 Then that file would also be reused inside the changelog to add hooks
 changes.

 Finally, it would be nice to have a way to filter on the marketplace
 between plugins that support that feature and the one who don’t as it will
 promote that practice even more

 As you can see there is a lot of room for improvement for that feature and
 I am not only accepting feedback about if this feature could be something
 good to the WordPress ecosystem but also suggestions to improve it.

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/7531>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org