Documenting non-existant elements

documenting PHP elements that don't exist in reality?

[madmac]

I'm writing an application with a bit of a unique plugin API. It will be a commercial application, and so I'm trying to write the code to make it easy to generate API docs, using phpDocumentor.

One critical aspect is that the docs contain all of the plugin hooks, what they do, and what sections of the application call them.

The last part is fairly easy, using the @uses tag.

However, the first part is somewhat more complicated, as the hook methods don't actually exist in reality... they only exist conceptually. What I mean is, the methods do not actually exist in the plugin controller class. The plugin controller basically only loads enabled plugins in their set loading order. It doesn't care or have any idea of what the plugins do. Each plugin then is just a separate class, each sharing a common constructor call, but from there, each can be completely different. It is the plugin(s) then that hold the hook method(s). If a called method exists in a loaded plugin, the controller will execute that call for that plugin's class method (and so on for each plugin in the loading order). Now, you might think how can the controller know if it exists or not and execute it if it has no knowledge of the method?... well it gets a little complicated, but basically, I utilize the magic __call() class method to facilitate this process.

All fine and dandy, but now when it comes time for the docs, I have no way to automatically document the plugin hook API, because it only exists conceptually in my mind.

Has anyone had any experience documenting elements that don't really exist? I know this must sound odd, but its true.

The best solution I have been able to think of, is to create a skeleton "plugin hook" class, in the bottom of the plugin controller class, whose sole purpose is to aid in documentation of the available hooks (i.e, it will never be called or initiated).

For example, it would just be something like:

<?php
/**
 * ServicePlugin API Hooks
 * 
 * long description here.
 *
 * @version 1.000
 * @author ME <[e-mail]>
 * @copyright Copyright 2005 , LLC. All Rights Reserved.
 * @package Plugins
 * @subpackage Service
 */
class pluginsServiceHooks {

/**
 * API hook to do something
 * @access public
 */
 function myHook() {
 }

/**
 * API hook to do something else
 * @access public
 */
function myOtherHook() {
}

}
?>

Does anyone see any potential problems with this approach, or have any better suggestions for documenting nonexistent API elements?

[edited by: jatar_k at 2:58 pm (utc) on Aug. 2, 2005]
[edit reason] generalized [/edit]

[jatar_k]

>> documenting nonexistent API elements

honestly madmac I can't think of any other way to do it. If it has to exist to be documented then your approach is the best you've probably got.

[moltar]

In reality you should write documentation first and then code. Writing docs first will help you find mistakes and problems in your program before a line of code is written.

As Charles Kettering puts it: "A problem well stated is a problem half solved".

So if you state your problem and how a piece of code solves it, you've done a big chunk of work for the future.

[madmac]

I write the API docs in the code as I go... the application is pretty large and attempting to write API docs before an API even existed, IMO would be pretty pointless (the code is very fluid while in the early development phases) and nearly impossible to do.

But I'm not entirely sure what your point is... You are saying I should write the docs up before I write the code... however, what I am talking about, the code will never exist. Not ever in the core application. Only the method call exists. The method itself does not now, nor will it ever exist in the core.

(well, actually now it does as a skeleton class, but only so that the hooks can be part of the API docs, so developers at least can have some reference of where they can plug-in at)