API list on website is out of date

[jrfnl]

A number of the questions being asked in the forum are to do with things people can fix themselves using the available filters and actions.

The API documentation is sorely out of date as a number of new actions/filters have been added since. Updating would be very helpful.

I believe it would also be helpful to make more prominent links to it, i.e.:
a) add a link to the API docs in the sticky WP forum post
b) add an API block on the Yoast website plugin page: http://yoast.com/wordpress/#wpseo Maybe with a nice 'free' button ?

I just answered a forum question which presented a typical use case for an undocumented filter.
Feel free to use the example I provide there as a use-case in the API documentation.

[jdevalk]

We need to automate this based on PHPdoc... So we can document new filters inline and have the documentation update automatically. Going to see what I can do.

[jrfnl]

PHPdoc based would be great, but would probably require quite some work, what about using the tokenizer functions just to get a quick list to start with ?

Want me to have a go ?

[jdevalk]

If you could have a go that'd be AWESOME :) pushing out another release
now, including your fixes. After that I'm going on holiday for the rest of
July, so, take your time :)

On Wed, Jul 3, 2013 at 4:16 PM, Juliette notifications@github.com wrote:

PHPdoc based would be great, but would probably require quite some work,
what about using the tokenizerhttp://nl1.php.net/manual/en/book.tokenizer.phpfunctions just to get a quick list to start with ?

Want me to have a go ?

—
Reply to this email directly or view it on GitHubhttps://github.com/jdevalk/wordpress-seo/issues/74#issuecomment-20418036
.

[jrfnl]

Hang on, got another fix, will send pull request ASAP

[jrfnl]

Ok, I'll try & have a go. Will set this up as an independent project which can then also be used by other plugin developers for documenting their actions & filters.

Enjoy your holiday!

[jdevalk]

Perfect, some others on Twitter showed interest too, pointed them here.

[jtgraphic]

I'm here from Twitter, ha.

Let me know what I can do. I'm not familiar with your build process or anything. Are you looking for something that will generate documentation on the fly or something you can run as a build process for each version? I've experienced both ways. I prefer to generate a README.md (or append it) when each version is tagged.

I'm here, use me.

[jrfnl]

@jdevalk Thanks!

@jtgraphic Welcome!

I've created a new repo for this project here: https://github.com/jrfnl/wp-plugin-hook-documentor

I'm currently thinking along these lines:

• Base class which will generate either a php array with all hooks and filters (+available documentation if it's there), a html string or a xml string - output either as a returned string/array or as a file.
• A frontend which will allow people to generate the list from any url/directory they have access to.

If people want static documentation, they can just use the frontend to generate it & save or use the class in their build process.
If people want dynamic documentation, they can include & call the base class to generate it on the fly.

I'm setting up a skeleton now and will commit it soon so you can see what I'm thinking.

Contributions very welcome ;-)

[jrfnl]

FYI: I've approached Adam Brown from the WordPress Hooks Database with the following email hoping we may be able to re-use some of the back-end code:

Dear mister Brown,

Thank you for your hard work in maintaining the WordPress Hooks database. I love it and use it regularly.

In a similar vain, some plugin developers would like to be able to provide better documentation about the hooks they provide within the plugins they develop.
You can view the start of our discussion here: https://github.com/jdevalk/wordpress-seo/issues/74

I've taken it upon me to create an application which plugin developers can use to do so. In effect this application would scrape the code for one particular plugin and provide a listing of the available hooks and filters in return.

Considering this, I was wondering whether you'd be willing to share (part of) your codebase behind the WP hooks database, either privately or via GitHub or a similar code repository for me to look through and possibly re-use.

I intend to release the application I'm building with a GPL-compatible open source license. I'm hoping you would be willing to release your code to me under a similar license.

I will, of course, give credit where credit is due and - if you are open to this - give back any code improvements I may make.

I look forward to hearing from.

Kind regards,
Juliette

[jrfnl]

I keep forgetting to push to GitHub, but in actual fact, I'm nearly done coding already ... ;-)

The logic I'm implementing for getting the right comment is as follows - feedback/suggestions very welcome!

1. Does the filter/action line have a comment or docblock on the line directly above it ? If so, we'll use that.
2. If not, and the filter/action is called from within a function -> crawl to the start of the function definition, if any other action/filter lines are encountered before the start of the function, stop crawling (as it would be ambiguous to determine for which action/filter the comment would be meant).
3. If no other action/filter lines are encountered, see if there is a docblock right before the start of the function definition. If so, look for any lines with the @api tag (phpDoc 2.0 standard) and use those.

For interpreting the @api lines, I suggest we use a similar standard as suggested in phpDoc for @ param / @ return etc.

@api    variable type   [variable name(optional)]   [Description of the variable(optional)]

Best to illustrate what I mean by that with two examples:

/* @api string  $string_to_be_filtered      Some information about the string to be filtered */
$string_to_be_filtered = apply_filter( 'my_filter', $string_to_be_filtered );

/**
 * This action allows you to do something during the execution of my plugin code
 * @api string      $variable1      Some information about passed variable
 * @api array|bool  $variable2      Some information about passed variable
 * @api mixed       $variable3      Some information about passed variable
 */
do_action( 'my_action', $variable1, $variable2, $variable3 );

If the documentation is retrieved via method 1 (docblock directly above the filter/action line), you can also use any of the other phpDoc tags such as @ example or @ see to add further information to the documentation.

I'd love to hear more views on this, so please pitch in with your opinions.

[jdevalk]

Sounds like a dream come true :-)
​
Would it also parse when a filter is used inline? Eg 

echo apply_filters( 'some_filter', 'text' ); 

​
 

—
Sent from Mailbox for iPad

On Fri, Jul 5, 2013 at 9:54 AM, Juliette notifications@github.com wrote:

I keep forgetting to push to GitHub, but in actual fact, I'm nearly done coding already ... ;-)
The logic I'm implementing for getting the right comment is as follows - feedback/suggestions very welcome!

1. Does the filter/action line have a comment or docblock on the line directly above it ? If so, we'll use that.
2. If not, and the filter/action is called from within a function -> crawl to the start of the function definition, if any other action/filter lines are encountered before the start of the function, stop crawling (as it would be ambiguous to determine for which action/filter the comment would be meant).
3. If no other action/filter lines are encountered, see if there is a docblock right before the start of the function definition. If so, look for any lines with the @api tag (phpDoc 2.0 standard) and use those.
   For interpreting the @api lines, I suggest we use a similar standard as suggested in phpDoc for @ param / @ return etc.

@api  variable type   [variable name(optional)]   [Description of the variable(optional)]

Best to illustrate what I mean by that with two examples:

/* @api   string  $string_to_be_filtered      Some information about the string to be filtered */
$string_to_be_filtered = apply_filter( 'my_filter', $string_to_be_filtered );
/**
 * This action allows you to do something during the execution of my plugin code
 * @api   string      $variable1      Some information about passed variable
 * @api   array|bool  $variable2      Some information about passed variable
 * @api   mixed       $variable3      Some information about passed variable
 */
do_action( 'my_action', $variable1, $variable2, $variable3 );

If the documentation is retrieved via method 1 (docblock directly above the filter/action line), you can also use any of the other phpDoc tags such as @ example or @ see to add further information to the documentation.

I'd love to hear more views on this, so please pitch in with your opinions.

Reply to this email directly or view it on GitHub:
https://github.com/jdevalk/wordpress-seo/issues/74#issuecomment-20505378

[jrfnl]

Yes, it already does ;-)

[jrfnl]

I'll commit in a bit so people can have a look at what's there so far.

N.B.: The code is currently still littered with inline tests and lots of notes which I use while developing, but the principle of it works already. I'm now working parsing the comments.

Once that's done, all that's left is pulling it all together, creating nice looking output and of course documenting it all.

[jrfnl]

First semi-working version (information gathering works, next is displaying it nicely) now pushed to GitHub. Have a play with it & let me know what you think ;-)

Oh.. also the getting of comments other than those directly above the hook call still need work too.

[Rarst]

This seems a little dated, but still open and so relevant.

I'd like to point out that in time since a lot of progress on https://github.com/rmccue/WP-Parser project happened and by now it should be usable to parse inline documentation, including the new inline docs for hooks which WP core adopted.

[Petervw]

bump

We'd like to see this fixed. :)

[Rarst]

This is on my list. :) To capture more recent decisions we will be running PHPDocumentor for API documentation and I need to look into making WP Parser code base provide capability to parse WordPress-specific code constructs to it (as opposed to using WP Parser in regular way and having to make WP installation, theme, and so on for it).

[omarreiss]

@atimmer and @andizer plan to update the docs in the beginning of February.

[atimmer]

This is an issue that never gets enough priority, we will be discussing this internally to find the best way to move forward.