Clean up API docs for color module

Killing extraneous whitespace is always good, and doesn't make the patch harder to review, so go for it! :)

This mostly looks good. A couple of things to fix:
a)

+ * @file
+ * Attaches the behaviors for the color module.

Refer to modules either as "the Color module" (capitalized) or "color.module" (without "the"). The latter makes a link on api.drupal.org so is somewhat preferable in API docs.

b)

      * It is also symmetrical. If: shift_color(c, a, b) == d,
-     *                        then shift_color(d, b, a) == c.
+     * then shift_color(d, b, a) == c.

I think the word "then" can fit on the first line here, if you are going to rewrap it.

c)

+    /**
+     * Focuses the Farbtastic on a particular field.
+     */

I don't think "the" is good here.

d)

- * Helper for hook_form_FORM_ID_alter() implementations.
+ * Alters the system_themes form for the color module.

What is system_themes? I can't find that in a search on api.drupal.org. Please use the name of the actual form function if possible (and follow by () ). See also (a) above. Also, maybe this should have an @see to the function above that is using it as a helper?

e)

- * Callback for the theme to alter the resources used.
+ * Alters the resources used in the html template.

html -> HTML.

f) Also maybe this should have an @see to the function that is using this? If it's really a callback, follow the "callback function" guildelines in this section (scroll down):
http://drupal.org/node/1354#functions
And same for the next callback function.

f)

+ * Blends two hex colors and return the GD color.

return -> returns

g)

+ * Converts a HSL triplet into RGB.

a -> an

h)

/**
 * Test color functionality.
 */
class ColorTestCase extends DrupalWebTestCase {

This needs an update:
http://drupal.org/node/1354#classes

i)

   /**
-   * Test to see if the provided color is valid
+   * Tests if the provided color is valid.
    */

The original wording here was OK, but without "to see", the "if" in your modified line should be "whether".

Ah.... let's see.

(d) - yeah, let's leave those functions completely alone for now and file a separate issue saying they are not being used and should be removed.

(e) - In that case, call it html.tpl.php directly (which will make a link to the file on api.drupal.org). If you want to use HTML in text as "the HTML template", yes it should be capitalized.

(f) - Ah, OK. So it was misdocumented as a callback in the original. I think adding an extra line to the docs saying something like "Themes can call this function to ..." would be helpful, yes. Putting an @see to the Bartik functions that call it is not necessary (on api.drupal.org, the list of calling functions is shown anyway).

I took a closer look at those functions. Maybe a better description would be:

(html function)
Replaces style sheets with color-altered style sheets.

A theme that supports the color module should call this function from its themename_process_html() function, so that the correct style sheets are included when html.tpl.php is rendered.

(page function)
Replaces the logo with a color-altered logo.

A theme that supports the color module should call this function from its themename_process_page() function, so that the correct logo is included when page.tpl.php is rendered.

A few files are still missing @file blocks. Other thank that, I think this patch is ready.

Regarding (d) from the discussion above -- let's not do *anything* to the docblocks for those function(s) that probably need to be removed. So this should not be here:

/**
- * Helper for hook_form_FORM_ID_alter() implementations.
+ * Alters the system_themes form for the color module.
  */
 function _color_theme_select_form_alter(&$form, &$form_state) {

While you're at it:

 /**
- * Form callback. Returns the configuration form.
+ * Form constructor for the configuration form for a particular theme.

This is probably just the color configuration form, right? The description here makes it sound like it's the whole config page for a theme, not specifically about colors.

And this needs a period at the end of the sentence:

+ * Constraint: if (ref2 == target + (ref1 - target) * delta) for some fraction
+ * delta then (return == target + (given - target) * delta)

And this needs an extra blank line between the @file docblock and the first function:

+/**
+ * @file
+ * Attaches preview-related behavior for the color module.
+ */
 (function ($) {

Read through the patch again and #8 and #9 have been fixed. Everything else looks correct as well.

+++ b/core/modules/color/color.admin.cssundefined
@@ -1,3 +1,7 @@
+ * @file
+ * Stylesheet for the adminstration pages of the Color module.
+ */

typo for 'administration'.

Otherwise looks great.

Discussed the comments for CSS and JS files here a bit with xjm. We strip comments for CSS during aggregation, but not JavaScript, so I bumped #352951: Make JS & CSS Preprocessing Pluggable to major.

11 days to next Drupal core point release.

Sorry, missed this before:

+++ b/core/modules/color/color.moduleundefined
@@ -112,7 +128,7 @@ function _color_page_alter(&$vars) {
+ * Retrieves the color.module info for a particular theme.

+++ b/core/modules/color/color.testundefined
@@ -6,7 +6,7 @@
+ * Tests color functionality.

@@ -52,7 +52,7 @@ class ColorTestCase extends DrupalWebTestCase {
+   * Tests color module functionality.

Should this be "the Color module information"? (Functionality, etc.)

Alrighty, re-RTBC. :)

Committed to 8.x. Thanks!

Pretty much a straight reroll; just the names of the CSS files have changed in D8. No commit credit please. :P

Looks good for d7, thanks!

Looks good, thanks!

Committed and pushed to 7.x.

I opened up #1808178: Further clean up of API docs for Color module to address additional issues about bringing Color module closer to D8 documentation standards. Reviews there are welcome.