file.inc documentation needs overhaul

aw, you had the right project the first time. documentation in code goes in the drupal core queue, under documentation component. :-)

+ *   -filepath - The path to the file after it has been processed and uploaded.  This 
+ *   will contain the unique filename if a unique name was generated.
...
+ *   -destination - The destination path that this file was uploaded to, including 
+ *   the file name and extension.

Having never used this function, I am a good subject for the "idiot test": On reading only this description, without the code below, I was unable to understand what the difference is between filepath and destination. I'll read the code now and possibly understand it, but consider clarifying it in the comment.

Addendum:

$file->filepath is the temp name for most of the function's work, but before the object is returned we get (unconditionally) this:

 $file->filepath = $file->destination;

It would probably be best to reflect in the comments that the two member's values are identical.

newbie eyes too :)

+ * -filepath - The path to the file after it has been processed and uploaded. This
+ * will contain the unique filename if a unique name was generated.
...
+ * -destination - The destination path that this file was uploaded to, including
+ * the file name and extension.

What is the difference between -filepath and -destination?

cross post.

In D7, there is already documentation on http://api.drupal.org/api/group/file/7 (click on "File interface" in Related Topics on http://api.drupal.org/api/function/file_save_upload/7 - generated from a header at the top of includes/file.inc). This doc page contains the common components of the file object. I would advocate not repeating that doc in every function that uses the same file object, but instead making it clear in @return for each of the file functions, where to look to find that information.

It appears that this particular function file_save_upload has added two custom components to the object:
- source
- destination

These two components appear to be unique to file_save_upload, so they should be documented in that function.

For Drupal 6, the corresponding file group page does NOT have the common components documented. So they should be added to http://api.drupal.org/api/groups/files via a header like what's in the D7 version of includes/file.inc (but possibly edited to be accurate for D6).

That's my opinion, anyway.

Had to search for a while to find out why the returned object of file_save_upload didn't contain filepath anymore.
My first clue come from #566798: Documentation problem with file_scan_directory: filepath => uri, but the documentation at http://api.drupal.org/api/group/file/7 made it clear.

Can this patch be applied, so it gets in the docs of file_save_upload() ?

The patch cannot be applied until someone fixes it up so it will pass review.

Attached is a revised patch for Drupal 7. It fixes up a couple of formatting issues in the doc, and documents return value for file_save_upload().

Documentation for file_save_upload now matches the "File interface" documentation nicely.

Committed to CVS HEAD. Thanks!

Need to do something similar for D6. Probably a bit more extensive. See comment #7 above.

Sheesh. Actually, the Drupal 6 doc for the entire file.inc file is a complete mess. It is mosly out of compliance with our doc header standards, filled with typos and punctuation/grammar errors, etc. Sigh. Not sure if anyone cares but me...

I totally care, and have a long train journey coming up :-D

Steven: Are you still planning on doing this?

I guess Steven is probably not planning on still doing this...

See also #841134: Description for the parameter $replace of file_save_upload() is not correct, which is a somewhat related D6 documentation issue in the same area of the same file.

The Drupal 7 fix did not include the correction to the $source variable in file_save_upload(). Shall I open a new bug report, or modify this one?

Probably a new issue.

I am cleaning up old 6.x documentation issues. At this point, we are not spending effort fixing them. Sorry.

So this one was D7 and it was fixed. Setting back to that.