[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  |  Resolution:
 Keywords:                    |
------------------------------+---------------------

Comment (by flexseth):

 > The only potential issue I see with that is how to recognize a hook is
 visual

 @coquardcyr - in the PHP Standards docs there are best practices for hooks
 that display information.

 > Functions: What does the function do?
 > Good: **Displays** the last modified date for a post.
 [https://developer.wordpress.org/coding-standards/inline-documentation-
 standards/php/#:~:text=Functions%3A%20What,for%20a%20post. Link to docs]

 So a well documented hook would look something like this:
 {{{#!php
 <?php
 /**
  *
  * my_awesome_plugin_before_title_hook
  *
  * Description: **Displays** content before the post title
  *
  * @version 1.0.2
  * @return  string
  *
  */
 add_action( 'my_awesome_plugin_before_title_hook', 'post_title' );
 function my_awesome_plugin_before_title_hook() {
   return {
     // HTML to output
   }
 }
 }}}


 If visual hooks were standardized and linted before passing the (already
 rigorous) plugin guidelines for review, it would be easy to build a plugin
 for display only hooks.

 IMO: With many new people coming into WordPress this could be a great
 improvement. Imagine someone wants to add a "Like" button to a certain
 part of the page. They can set this up on Facebook, but don't exactly know
 how to do it.

 But there's an easy to use plugin boilerplate, and documented display
 hooks.

 They could roll a plugin, add the hook, and enter the code (usually
 JavaScript)

 Instantly a developer :)

 ''This code is meant to represent pseudocode-ish and not functional code''

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