File.inc function documentation: clarify that several functions _must_ be fed a stream wrapper URI [#573288]

When trying to adopt a module to D7 i ran into the issue that system_retrieve_file() was causing file_unmanaged_copy to fail with a message that it could not copy to the given destination - which was a plain filesystem path, without stream wrapper stream. This patch clarifies the function documentations in file.inc to explicitly state that a stream wrapper is mandatory.

Comment	File	Size	Author
	file-inc-clarify-documentation-stream-wrappers.patch	4.92 KB	eMPee584

Comments

Comment #1

eMPee584 commented 15 September 2009 at 10:48

Issue tags:

+Documentation

(tagging..)

Comment #2

cburschka

they

commented 31 December 2009 at 18:29

Status:

Needs review

» Needs work

+++ includes/file.inc
@@ -513,8 +513,8 @@ function file_save(stdClass $file) {
+ *   This must be a stream wrapper URI. If this value is omitted, Drupal's
+ *   default files scheme will be used, usually "public://".

This sounds a bit ambiguous. A "files scheme" is not a destination - does this mean the root folder of public://? The same applies to the rest.

This review is powered by Dreditor.

Comment #3

drewish commented 19 April 2010 at 23:04

Status:

Needs work

» Needs review

I agree that it's not perfect but since even should->must is such a clear improvement we should go ahead and commit this. Resetting the status to test that the patch still applies.