[CarCdr]

Dean,

While there is some documentation that could be extracted from the script header, this is not like JavaDoc. This is not a documentation system. It is not meant to document the mod, or like JavaDoc and systems that preceded it, to document functions, variables, etc. The only thing in common with JavaDoc was my choice of '@'.

The main thrust of the system is functionality, not documentation. What it is meant to do:

• Allow of single source install. Put the file in the main forum directory -- that's it.
• The single source supports:
  1. The script itself, if the mod is indeed a script that is run by users, such as forum/display_stats.php. (Some mod's do not actually run a script -- they just change something about vB or install new options/templates, etc.)
  2. Common page operations like building a navbar and forum_jump. In this simple example, they were listed in "@page_options". Fact is, why have every mod that needs it include code for such things. If vBulletin changes anything regarding navbar or forum_jump, all the mod's would have to be fixed.
  3. Optional install. The admin would install only if the default options, phrases, and templates required changing. Install would support installation of only those pieces that the admin wants to change. Without the install, the defaults delivered in the single file are used.
  4. SDK functionality and independence through the "VBMOD_" functions. On a new release of vBulletin, the SDK would be checked for incompatibilities and updated. Site the world over would simply upload the new "VBMOD" package before the install the new vBulletin. This is much better than having to update all their mod's. (Sure, they may still have some mod's that require updating, but by using an SDK, they are better protected from vBulletin changes.)

For all mod's that require a new user script, phrases ($vbphrase), admin-side options ($vboptions), and mod-specific templates, the admin would not have anything to do other than copy the file to the forum home directory.

The more difficult aspects not yet supported in what I am proposing, are supporting changes to vB-delivered PHP code or vb-delivered templates, but we'll get to that discussion later. Let's start this discussion with what is more easily done.

Cheers

ps: For anyone worried about the script having to read the script header (the big comment at teh beginning) everytime it is run, it would be easy enough to use a cache and only read the file only if it has been modified.