Update doxygen header of Archive_Tar::__construct() function to meet current Coding Standards.

Several problems here:

+    * Returns a new Archive_Tar Class object.

I don't think we use "Class object" anywhere else in the code. Should probably just say "Returns a new Archive_Tar object." Class seems redundant to me, and it definitely shouldn't be capitalized if it is used.

+    * identifying it by the name of the tar file. If the compress argument is

Please use the name of the parameter, which I think is $p_compress. It is more precise than "the compress argument". Also, this information should be in the @param section, not in the general function header, as it is specific to that parameter.

+    *   The name of the tar archive to create

Does not end with a period.

+    * @param mixed $p_compress
+    *   Can can be NULL, TRUE, 'gz' or 'bz2'. This parameter indicates whether
+    *   gzip or bz2 compression is required.  For compatibility reasons the
+    *   boolean value TRUE means 'gz'.

One space between sentences, not two. Start with the parameter description, then put the allowed values. Don't say "this parameter indicates", just say "Indicates". Probably you can combine the "Can be ... TRUE" with the explanation of what TRUE means, something like:
Possible values: NULL, 'gz', 'bz2', or TRUE (equivalent to 'gz').
Actually, these would be even better as a list that explains what they mean.

The '@param mixed' style also needs to be changed to the preferred format '@param NULL|bool|string'.

However, a zero byte patch will not change anything!

Reading the revised docblock documentation, I wonder what will happen if one were to specify $p_compress as FALSE. This is no fault of the revised documentation. However, it points out the problem with partial/incomplete code paths. Could this be revised to be more clear?

One more thing I just noticed -- the /** and the * lines do not line up according to our standards on this function.

And this line still needs a period at the end:

+    *   The name of the tar archive to create

Also, the standards at http://drupal.org/node/1354#functions do not include "true|false" but instead "bool" for return value docs. I am not sure what we should do about NULL though -- using a lower-case "null" doesn't seem right, but we don't have a standard...

There are several functions in core that have a @return profile of whatever (string, int, object) | FALSE | NULL. How should these be documented when TRUE is never returned and hence should never be considered a valid return value? In such cases, FALSE seems more appropriate than bool.

In this case though, it seems like '@return bool' is appropriate since both are valid return values.

See http://drupal.org/node/1295500#comment-5068622 for a discussion of the reformatting (in this case, I would only reformat the docblocks for the file at a time when disruptions are OK, or on an individual basis when there is a doc problem)....

Come to think of it, this whole issue is just about formatting of that one docblock anyway. Maybe we should postpone this whole reformat, and do the whole file at once, during the first week in November?

Sigh. If the people who added this to Drupal Core had followed the standards in the first place....

Angie/webchick may say "when in doubt, do what PEAR does", but our expressed doc/coding standards are not the same as that project's doc standards.

Anyway, if we're trying to maintain this to be the same as PEAR as possible, then we should just leave it as-is and maybe put a note at the top of the file noting that? I'm sure we don't alter JQuery files and other things that we import from other projects... we probably shouldn't alter this either, but just be aware that it isn't "our" code?

Can you ping someone with authority on this in IRC to get some opinions on whether we should be trying to update any coding/docs standards in this section of the code then? Postponing until I hear back...