Documentation for file_scan_directory is incorrect [#623276]

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!

Comment	File	Size	Author
#10	0001-Issue-623276-Fixed-documentation-for-file_scan_direc-D6.patch	2.1 KB	mr.baileys
#9	623276-D6.patch	1.88 KB	jhodgdon
#6	623276.patch	2.76 KB	jhodgdon

Comments

Comment #1

jhodgdon

she/her

English

commented 4 November 2009 at 18:13

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.

Comment #2

steven jones commented 4 November 2009 at 18:15

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.

Comment #3

jhodgdon

she/her

English

commented 4 November 2009 at 18:34

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

Comment #4

steven jones commented 4 November 2009 at 22:09

The drupal 6 docs are wrong too.

Comment #5

jhodgdon

she/her

English

commented 4 November 2009 at 22:46

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!

Comment #6

jhodgdon

she/her

English

commented 4 November 2009 at 23:03

Status:

Active

» Needs review

Status	File	Size
new	623276.patch	2.76 KB

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.