Speaker notes

=>

Notes: The theme of this talk will be:

developing dynamic documentation for WordPress plugins, APIs and hooks.

With some live demonstration and using real examples drawn from my experiences this talk will attempt to explain how I’ve gone about developing, documenting, delivering and supporting the [loik] suite of [wp] plugins.

WordPress, WooCommerce, EDD, Jetpack figures

Notes:
debug output to screen

Notes: Click on the links to find out about these PHP functions.

Also, if you ever want to provide some PHP code for others to cut and paste then take a look at var_export().

Inline documentation of PHP code

Notes: My ex-colleague Joe … truly believed that the documentation of the system was in the code. He didn’t even trust comments. So what’s wrong with this code? Answer: Don’t know. How can we tell what it was supposed to do?

GeSHI – Generic Syntax Highlighting is nice to have… but WIBNI you had a little more.

About me

Notes: Herb Miller is a web developer based in Rowlands Castle, Hants.

Owner of Bobbing Wide and the creator of oik-plugins – lazy smart shortcodes and NOW, WordPress themes.

This page was built almost entirely from oik shortcodes.

@herb_miller @bobbingwide @oik-plugins

About

Notes:
The story so far

Notes: So how have I gone about this development. What’s the chronology?
Tracing

Notes:

Problem determination – debugging

Notes:
Plugins used

Notes: This table doesn’t actually list the plugins used in this talk. It’s showing the active plugins. So [bw_plug smart-bbboing] may be missing from the list.

WordPress startup

Notes: Click on the image for more details.

custom post types and custom fields

Notes: In WordPress – content is stored in wp_posts and metadata stored in wp_postmeta. WordPress provides APIs for the DB end – CRUD – Create, Read, Update, Delete. But it doesn’t provide functionality to display the content or accept input: Theme and form. You also need to be able to extend the API set for different types of fields. There’s no standard framework to define “fields” and their relationships with post_types. Each CPT plugin rolls its own solution. The oik base plugin provides the base APIs shown here. oik-fields provides the theming and forming.

About WordPress

Notes: WordPress is rather popular. If you want to understand WordPress development then it’ll be a good idea to get a firm grip on each of these terms.

Size of the problem

Notes: What’s the size of the problem? Over the past 4 years I’ve developed quite a lot of code. Some of it’s available in WordPress SVN, the rest in the plugin source. Initially I just wanted to document the shortcodes. Then I wanted to document the APIs. Most recently I’ve focussed on WordPress hooks: actions and filters.
Debug bar plugin

Notes:
WordPress start up – worked example

Notes: As the video is running – assuming it is, you can say what WordPress does.

If I remember I’ll tell you what each of the balls represents later on.

For more Animusic see http://www.youtube.com/watch?v=vfQijIjXHN8

Performance – does it matter

Notes:
API documentation should cover

Notes: See the WordPress codex for the documentation that is maintained there. The documentation is in a wiki. Each time an API is updated then it may be necessary to updated the documentation as well. That’s a lot of work. WordPress has over 300 KLOC.
Plugins and APIs

Notes: Plugins are made up of files. Each PHP file contains APIs. API’s attributes:

  • name
  • noderef to plugin
  • sourcefile
  • calls – noderef to APIs that it calls – multiple links
  • hooks – noderef to action & filter hooks – multiple links

I’m doing it wrong

Notes:

My development environment

Notes: I use a laptop running Windows 7. It’s a WAMP setup: Windows, Apache, MySQL, PHP – each individually installed. I use a number of simple tools to help me create and manager code and content. I’m often using two screens. If it’s working there’ll be an iframe connecting to more details at herbmiller.me
Backtrace log

Notes:
AND then you see…

Notes:
Dynamic documentation

Notes: End users want the documentation for a plugin to show: features, examples, tutorials, options pages, and things they interact with such as shortcodes. Developers want to know about versions, APIs, including hooks and filters they can use. The plugin developer wants the system to automatically document this information.
docBlock analysis

Notes: Using the PHP Reflection function and logic copied and cobbled from phpDocumentor2 it’s fairly easy to extract information from the docBlock comment and use this where needed in the API documentation.

I only used a tiny subset of the phpDocumentor2 code. And I had to make it work on PHP 5.2. So I needed to de-namespace it.

Could do better

Notes: Now that WordPress 3.7 contains in-line documentation for actions and filters, I need to extract the information to include in the “oik_hook” post_type instance. Or maybe just the location of the docblock?

My code doesn’t detect callbacks, can’t handle dynamically generated hook names or dynamically generated API names.

Nor does it handle OO or “immediately executed” code.

The problems I am trying to solve

Notes: At bobbing wide and oik-plugins I design, develop, deliver, support and maintain WordPress websites, plugins and themes. Both for normal WordPress installations and also WordPress multisite. The plugins need to be efficient, powerful, helpful AND do the job they’re intended to do. For power users, designers and developers the [shortcodes] need to be well documented with lots of examples. For developers there also needs to be a ton of documentation: RTFM not TLDR

Performance: so what bothers you?

Notes: Does it matter how fast the code is? Can you just attach a cacheing plugin?

I’ve been developing the i18n, l18n versions of my oik-plugins and have counted the number of translations performed to display the [wp] login page.

Performance: does it matter part 2

Notes: On my PC it takes: 0.13 seconds to translate 2300 strings and 0.25 seconds to load 280 average sized .php files 0.38 seconds of useless work.

So in the video each ball represented a string being translated?

Where can we get that from?

Notes: We need to extract information from the phpdoc block and merge it into the documentation.

http://en.wikipedia.org/wiki/PHPDoc

Doing it wrong alert – hyphens being converted to HTML entity Also note that I have slightly altered the “long description” so it fits on one line. 🙂

The implementation

Notes:
API parsing

Notes: Another “doing it wrong”. [apis d,b,c,a] not respecting the order in which the API names are typed. AND if you follow the links you’ll find the links to WordPress API reference isn’t right either. DOH! Herb 11 Nov 2013.

Further reading

Notes:

Targets achieved?

Notes: During the preparation of this presentation I have documented 10 plugins, three of which are brand new for the presentation. There are over 1,300 APIs documented and over 70 hooks.

I have found x instances of doing it wrong, fixed y problems and found z things to add to my TODO list.

Performance: a potential solution

Notes:
uppity()

Notes: Let’s generate the documentation ON THE FLY. All we need to know is: where to find the code and the in-line documentation.
Final uppity API documentation

Notes: But I also want to know the usage of this function. I want to be able to navigate the code. One way is to use grep. Another to use an IDE. But what about dynamic systems – with plugins that extend base behaviour?
Call tree

Notes: When defining an API we use WordPress actions to insert meta data for each function that calls a recognised API. In order to get the system to realise that foo() calls bar(), it has to know that foo() and bar() are “our APIs”. On the second parse of foo() we are then able to record the fact that foo() calls bar(). When displaying the who calls me list we access the metadata by meta_value.

WordPress provides some amazingly powerful APIs, e.g. get_posts(). I expose the parameters to some seemingly innocent looking shortcodes.

The out takes

Notes: At the time of writing ( Nov 11, 1pm) I have no idea what the “L” is.

Questions?

Notes: The quote comes from my manager, 30 years ago. He was trying to suggest that there are multiple points from which a problem can be viewed. I don’t think he was suggesting that his answer was the right way.

Asking questions is good. The answer might not be the one you want to hear. But it may help you determine what the right answer should be.

oik-batch

Notes: oik-batch runs a subset of WordPress. For each file in the plugin, for each API, it sends an http request to create the API using admin-ajax. The WordPress server handles the request by invoking the action requested. The API is created or updated. The call tree gets updated on the second and subsequent passes. For this to work properly the same version of the code is required on both client and the server. The plugin does NOT need to be activated, but it does need to be defined ( post_type: ‘oik-plugins’ ).

HELP WANTED – How to cater for PHP Warnings?

Notes:

Performance – conclusion

Notes: wp-login is displayed < 1% of the time. It's more important to tune your home page, the most visited page and perhaps wp-admin. See also http://www.guffsturdpolish.com/
hooks and filters

Notes: When we parse bobbing_loaded() we see add_action() telling us that the action hook “oik_loaded” is implemented by “bobbing_init”. If the hook had not been encountered we create it. Since the bobbing_init API is known we can log “bobbing_init” as one of the implementers of “oik_loaded”.

If you think the terminology is confusing then, don’t worry, you’re not alone. If it hasn’t helped you then that’s a shame; it’s helped me!

Another DIW – I really should look into [bw_plug name=footables]

Summary

Notes: Tell em what you were going to tell em. Tell em what you actually told em. Tell em something else but don’t spend too long on it. Any time left for questions?
Appendices

Notes:
Table of Contents

Notes: In the first div we see the top level “oik_presentation” pages. In the second div (rhs) we see the hierarchy of pages.

About Bobbing Wide

Herb Miller is the web designer, web developer at Bobbing Wide, based in Rowlands Castle.