The doxygen for file_scan_directory is wrong and has been wrong for many versions of Drupal.

The docs state about the $key argument:

'key' The key to be used for the returned array of files. Possible values are 'filepath', for the path starting with $dir, 'filename', for the basename of the file, and 'name' for the name of the file without an extension. Defaults to 'filepath'.

'filepath' is not a valid value for this option, it should be 'uri', though I'm not entirely sure what that means in terms of a return value, so I'm not sure what its description should change to!

Files: 
CommentFileSizeAuthor
#10 0001-Issue-623276-Fixed-documentation-for-file_scan_direc-D6.patch2.1 KBmr.baileys
#9 623276-D6.patch1.88 KBjhodgdon
#6 623276.patch2.76 KBjhodgdon
Passed: 14630 passes, 0 fails, 0 exceptions
[ View ]

Comments

It looks like the doc for Drupal 6 http://api.drupal.org/api/function/file_scan_directory/6 matches the function, for the $key argument. So I am not sure about "has been wrong for many versions of Drupal".

However, in Drupal 7:

$options['key'] = in_array($options['key'], array('uri', 'filename', 'name')) ? $options['key'] : 'uri';

So the default is 'uri' and the options are 'uri', 'filename', 'name'.

So in my opinion, this does need a fix for Drupal 7 only.

You are entirely correct, file_scan_directory has incorrect documentation for the return value, in Drupal 6:

An associative array (keyed on the provided key) of objects with "path", "basename", and "name" members corresponding to the matching files.

Ummm... Do you think the Drupal 6 doc is correct or incorrect?

The drupal 6 docs are wrong too.

Ah, I see. In Drupal 6, the $key parameter description is correct, but the Return Value part is incorrect. In Drupal 7, it looks like just the $options['key'] description is incorrect, and the Return Value section is correct.

Thanks!

Status:Active» Needs review
StatusFileSize
new2.76 KB
Passed: 14630 passes, 0 fails, 0 exceptions
[ View ]

Here's a patch for Drupal 7. It fixes the problem (I think) and also some formatting issues with that particular function's doc header to bring into compliance with coding standards. And a couple of minor grammar/wording tweaks.

If accepted, please mark as Drupal 6 issue / "active" so we can also patch Drupal 6.

Status:Needs review» Fixed

Committed to CVS HEAD. Thanks.

Version:7.x-dev» 6.x-dev
Status:Fixed» Active

So now in D6, the return value is:

An associative array (keyed on the provided key) of objects with "path", "basename", and "name" members corresponding to the matching files.

But should read:

An associative array (keyed on the chosen key) of objects with "filename", "basename", and "name" members corresponding to the matching files.

Status:Active» Needs review
StatusFileSize
new1.88 KB

Here's a doc fix for Drupal 6. Fixes issue in #8 above, as well as a few other minor issues (line wrapping, punctuation, wording).

Status:Needs review» Reviewed & tested by the community
StatusFileSize
new2.1 KB

This is RTBC. Straight re-roll attached since patch from #9 applied with an offset.

Please don't add a -D6 suffix to D6 patches. It causes the testbot to ignore them. See help text on the attach field.

Status:Reviewed & tested by the community» Fixed

Thanks, committed.

Status:Fixed» Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.