In the Doxygen formatting conventions doc, it says that files should be documented with the @file directive and gives the following example:
<?php
// $Id: theme.inc,v 1.202 2004/07/08 16:08:21 dries Exp $
/**
* @file
* The theme system, which controls the output of Drupal.
*
* The theme system allows for nearly all output of the Drupal system to be
* customized by user themes.
*/Note the @file line in particular.
Further down the same doc, under the section on "Documenting theme templates", the @file directive example is different:
<?php
// $Id$
/**
* @file forum_list.tpl.php
* Default theme implementation to display a list of forums.
*
* Available variables:
* - $forums: An array of forums to display.
*
* Each $forum in $forums contains:
* - $forum->is_container: Is TRUE if ...........
*
* @see template_preprocess_forum_list()
*/In the first example, the @file directive was just @file whereas in the second it is followed by the filename, @file forum_list.tpl.php. I would like this to be more consistent. I would prefer if we just decided on one convention which would be used on all files, regardless of file type.
Personally, I'm in favour of removing the need for the filename, and have some reasons:
- First of all, the filename is already specified in the
$Id$line. In the example above, it's just $Id$, but this is filled out to include the filename and version information when the file is committed to CVS. I don't see any benefit to having the filename specified again in the @file section. - Have this filename here kinda messes up the API documentation. See http://api.drupal.org/api/files and look at any of the .tpl.php file entries, the filename is stated again in the file description and also appears in the file description on the file's documentation page. It doesn't cause problems per se, it just doesn't look clean.
- My last point is fairly minor. The Coder module already has checks in place for the @file directive, but expects nothing to follow it on the same line. Changes will be required to this module if we are to keep the filename specification.
Cheers,
Stella
+1 from me; stella, merlinofchaos, and I had discussions of it. --Morbus Iff.
+1 from me, too. --sun (PS: A discussion would probably have been more appropriately ;)
+1 - since that's 3-4 of us, I updated the page to remove that one filename from the example too --catch
Excellent, now I just need to provide patches to update the template files in core. Thanks - Stella