filter_filter api page is out-of-date

Issues with API documentation go in the Drupal queue, not Documentation.

It looks like this is an issue in D7 as well as D6 and D5.

The problems I see with the API doc for filter_filter():
- Description does not list all of the included filters.
- Description uses different names for the included filters from the names the module actually uses.
- Description for the HTML filter doesn't say what it actually does (limit HTML tags)
- Description for the URL/email filter has a completely wrong description.

Probably the D7 issue should be fixed first, then the patch ported to D6 (which will involve removing a few lines of the description, as D7 has more filters than D6). Are we still fixing D5 too?

Here is a patch for review, for D7.

"Implementation of" has changed to just "Implement" in D7. There should also be a gap between the initial one-line function summary and the rest of it.

Ah.

It appears also that the doc style in this file uses "Do something" rather than "Does something" in descriptions of functions. I am not sure why, since "Does something" is standard elsewhere in the software industry, and has been for decades. See, for instance http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide :

Use 3rd person (descriptive) not 2nd person (prescriptive). The description is in 3rd person declarative rather than 2nd person imperative.
- Gets the label. (preferred)
- Get the label. (avoid)

So the decision should have been to use "Implements" rather than "Implement". But that's a separate issue. Where/when was this discussed?

Anyway, I'll stay consistent with the rest of the file and D7, good decision or bad... how's this patch?

3rd-person is also the standard for Pear PHP doc:
http://www.php-editors.com/pear_manual/standards.sample.html

 /**
     * Registers the status of foo's universe
     *
     * Summaries for methods should use 3rd person declarative rather
     * than 2nd person imperative, begining with a verb phrase.
     *
     * Summaries should add description beyond the method's name. The
     * best method names are "self-documenting", meaning they tell you
     * basically what the method does.  If the summary merely repeats
     * the method name in sentence form, it is not providing more
     * information.

Forgot to change status

I filed a separate issue on the question of 1st person vs. 2nd person #487802: Function doc standard for Drupal is non-standard in industry

Until (or unless) that issue results in a change in coding standards, the current patch conforms to the current standards, I think.

Looks good to me. Marking RTBC so I can commit it later.

Committed to CVS HEAD. Thanks!

This still needs to be ported to D6.

Are we patching D6 documentation still? The reason I am asking is that I have 2 or 3 simple doc patches for D6 marked "needs review" that have been in the queue for as long as 6+ weeks with no action. I don't want to waste time porting this patch to D6 if there is little chance it will be committed.

jhogdon - I think patches will still get committed, but Drupal 6 patches don't show up in Drupal 7 patch queues from contributor links - which means they generally have a lot less eyes on them.

I got that impression. ;}

It would be nice if doc patches for api.drupal.org (which is probably much much more highly used right now on D6 than D7, I would think) got more attention... sigh. I guess I could do my part and review some. :)

Here is a patch for D6. It looks a bit different from the D7 patch (filter names are different and D7 has one filter D6 lacks). So it probably needs a review for accuracy before application.

Once for all, I finally took the time to document the proper and *required* syntax for lists'n'stuff in Doxygen: http://drupal.org/node/1354

The syntax of this patch needs work. The code D7 was fixed already.

OK, this one has better (I hope) formatting.

This looks good.

The patch is more than a year old. Did you verify that it still applies to the Drupal 6 source?

patching file modules/filter/filter.module
Hunk #1 succeeded at 610 (offset 9 lines).

I just tested it, I guess it would still apply cleanly.

Thanks!

Superb, thank you, committed, pushed.