Improve comments for function base_path()

Why does every second line intends with an additional space? We don't do that elsewhere in our code, so let's fix that up.

The second paragraph seems to have one 'at' or one 'into' too many -- does it have a grammar issue? (I'm not a native English -- just pointing things out.)

Other than that, it would be _great_ to have better documentation for this function. Thanks for your help!

For me its very clear now.

By changing example 2, this note is not needed anymore:

* NOTE: base_path prefixes "/" onto the returned path but
* does not suffix one. See examples below.

Looks good. Committed to CVS HEAD. Thanks.

Should it be ported to 6?

Patch against DRUPAL-6
Forget to change status

 /**
- * Returns the base URL path of the Drupal installation.
- * At the very least, this will always default to /.
+ * Returns the base URL path of the Drupal installation, i.e.,
+ * the directory where Drupal is installed. At the very least,
+ * this will return "/".

PHPDoc function summaries need to be on one line. Additionally, there needs to be a blank PHPDoc line between the PHPDoc summary and PHPDoc description. Please revert the summary to the original and add a blank PHPDoc line before the description.

In general, comments should wrap at 80 chars. The comments in this patch are wrapping at 65 chars (with 1 exception).

+ * NOTE: base_path prefixes and suffixes a "/" onto the returned

Use a trailing () when referring to function names (i.e. base_path()). NOTE: is superfluous here, the entire description is a note.

+ * Example #1: Drupal installed at "http://yoursite.com" means
+ * this will just return "/" because the path is empty.
+ *
+ * Example #2: Drupal installed at "http://yoursite.com/drupal/folder"
+ * means this function will return "/drupal/folder/".

No need to wrap URLs in quotes. Additionally, any example URLs should always use example.com. There are plenty of duplicated words in both examples, a simple list would do better:

* Examples:
* - http://example.com returns "/".
* - http://example.com/drupal/folder returns "/drupal/folder/".

Much better.

 /**
+ * Returns the base URL path (i.e., directory) of the Drupal installation.
+ * 

According to http://drupal.org/node/1354 [which could really use an URL alias], The first line of the block should contain a brief description of what the function does, beginning with a verb in the form "Do such and such" (rather than "Does such and such").

This was already wrong before, so let's fix it completely.

+ * not empty. See examples below.
  *
+ * Examples:

As you can see in http://api.drupal.org/api/function/base_path/7, the See examples below. is a bit superfluous. ;)

+ * @return
+ *   The base URL path (i.e., directory) of the Drupal installation.

Simple helper functions that just return something do not necessarily need a @return directive. In this case, all of @return is identical to the function's summary, so, superfluous.

Much better.

Now we have:

+ * Return the base URL path (i.e., directory) of the Drupal installation.
+ * 
+ * At the very least, this will return "/".
  *
+ * base_path() prefixes and suffixes a "/" onto the returned path if the path is 
+ * not empty.
  *

Many lines, and I'd even say that the first paragraph makes more sense after the second, i.e.

+ * Return the base URL path (i.e., directory) of the Drupal installation.
  *
+ * base_path() prefixes and suffixes a "/" onto the returned path if the path is 
+ * not empty. At the very least, this will return "/".
  *

Probably no longer related after this change, but please also make sure that blank PHPDoc lines are really blank:

+ * 

i.e. no white-space after the asterisk.

Committed to CVS HEAD. Thanks!

So let's improve D6 branch
Parch against current DRUPAL-6

one trailing space less

#30: 0001-Issue-432864-by-mcrittenden-andypost-Improve-comment.patch queued for re-testing.

Compared comment text against 7.x patch OK. However, patch has aged and it is not word-for-word identical to current 7.15 but has the same meaning, so rerolling seems overkill and might not get enough interested reviewers. Let's close this one.
Patch still applies and passes OK, trivial comment changes.

30: 0001-Issue-432864-by-mcrittenden-andypost-Improve-comment.patch queued for re-testing.