Bug #57852 Redundant and unused 'Comment' option/column
Submitted: 29 Oct 2010 17:39 Modified: 27 Jan 2011 18:46
Reporter: Peter Laursen (Basic Quality Contributor) Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.5.6 OS:Any
Assigned to: Paul Dubois CPU Architecture:Any
Tags: qc
Triage: Triaged: D4 (Minor)

[29 Oct 2010 17:39] Peter Laursen
Description:
1) 
http://dev.mysql.com/doc/refman/5.5/en/create-table.html
... lists ONE comment option

index_option:
....
  | COMMENT 'string'

2)
http://dev.mysql.com/doc/refman/5.5/en/show-index.html
.. returns TWO comment columns

Comment:
Various remarks.

Index_comment:
Any comment provided for the index with a COMMENT attribute when the index was created.

There is no way to set 'Comment' as per 2) as far as I can see.  COMMENT as per 1) sets Index_comment as per 2) (only)

How to repeat:
CREATE TABLE `test`.`indexcmt`(`id` INT NOT NULL AUTO_INCREMENT ,`txt` VARCHAR(10) ,PRIMARY KEY (`id`));
ALTER TABLE `test`.`indexcmt` ADD INDEX `NewIndex` (`txt`) COMMENT 'blah';
SHOW INDEX FROM `test`.`indexcmt`;

-- Returns what columns are documented in 2nd link, but note that 'Comment' column is empty and 'Index_comment' column reads 'blah'

Suggested fix:
Looks like 'right hand' and 'left hand' did not communicate here. Remove one of the comment columns from SHOW INDEX. There is no way to 'fill' more than one as far as I can see (from CREATE/ALTER TABLE). 

If I am wrong a better description than (the non-informative) 'Various remarks.' is required.
[10 Nov 2010 23:05] Sveta Smirnova
Thank you for the report.

Verified as described: 2 columns are ambiguous.
[21 Jan 2011 10:04] Magnus Blåudd
There is also a tab missing in the column headers between Comment and Index_comment -> it looks like last  column is named CommentIndex_comment.
[21 Jan 2011 10:14] Magnus Blåudd
Hmm, scratch that. It was only in my Terminal :(
[21 Jan 2011 10:26] Magnus Blåudd
Have checked the code and it looks like "Comment" is a free text field for things to note about this index that doesn't get it's own specific column, currently it can get the value "disabled" or empty string. I think "disabled" indicates that the index is currently disabled. This is an old feature.

The "Index_comment" on the other hand is the user provided COMMENT for the index set in CREATE TABLE and is new for 5.5. Nice thing to note with 5.5 is that the comment for an index now can be significantly larger than before. Before 5.5 it was not possible to see the comment for an index set with SHOW INDEX.

Hope this helps to explain why there is both a "Comment" and "Index_comment" in 5.5.

Closing as Won't fix.
[21 Jan 2011 10:26] Magnus Blåudd
Have checked the code and it looks like "Comment" is a free text field for things to note about this index that doesn't get it's own specific column, currently it can get the value "disabled" or empty string. I think "disabled" indicates that the index is currently disabled. This is an old feature.

The "Index_comment" on the other hand is the user provided COMMENT for the index set in CREATE TABLE and is new for 5.5. Nice thing to note with 5.5 is that the comment for an index now can be significantly larger than before. Before 5.5 it was not possible to see the comment for an index set with SHOW INDEX.

Hope this helps to explain why there is both a "Comment" and "Index_comment" in 5.5.

Closing as Won't fix.
[21 Jan 2011 10:29] Peter Laursen
I am not trying to make a lot of trouble but shouldn't it be reclassified as a documentation bug?  The explanation given here should go int docs IMHO.
[21 Jan 2011 10:41] Magnus Blåudd
Sounds good Peter. Thanks!
[27 Jan 2011 18:44] Paul Dubois
"1) 
http://dev.mysql.com/doc/refman/5.5/en/create-table.html
... lists ONE comment option

index_option:
....
  | COMMENT 'string'
"

Actually, this appears both for column_definition and index_option.

"2)
http://dev.mysql.com/doc/refman/5.5/en/show-index.html
.. returns TWO comment columns
"

Right, and they are both documented on this page.
However, I'll update the description for Comment to:

Information about the index not described in its own column, such as
"disabled" if the index is disabled.
[27 Jan 2011 18:46] Paul Dubois
Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.