MySQL Bugs: #57852: Redundant and unused 'Comment' option/column

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

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.

Thank you for the report.

Verified as described: 2 columns are ambiguous.

There is also a tab missing in the column headers between Comment and Index_comment -> it looks like last  column is named CommentIndex_comment.

Hmm, scratch that. It was only in my Terminal :(

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.

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.

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.

Sounds good Peter. Thanks!

"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.

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.