MySQL Bugs: #34413: "declarations for plugin implementors" in plugin.h should be documented

Bug #34413	"declarations for plugin implementors" in plugin.h should be documented
Submitted:	8 Feb 2008 12:57	Modified:	18 Jan 2010 14:20
Reporter:	Roland Bouman	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.1.22-rc	OS:	Any
Assigned to:	MC Brown	CPU Architecture:	Any

Description:
plugin.h (include/mysql/plugin.h) is the formal interface for creating plugins. In plugin.h we find a number of declarations which are to be used by plugin-implementors as a public interface to some of the server's internals. 

Unfortunately many of these are not documented in the manual, nor do they have comments in plugin.h.

This effectively means that it cannot be used as a public interface - plug-in implementors still need to grep the source code to see the implementation of the functions and hopefully find some meaningful comments there. In many cases, the implementations are not commented on either, which means the plug-in implementator will have to resort to guessing.

How to repeat:
Oopen include/mysql/plugin.h, 

see declarations following line 266:

/*
  the following declarations are for use by plugin implementors
*/
..
..

and declarations following line 667:

/*************************************************************************
  Miscellaneous functions for plugin implementors
*/

Suggested fix:
Please provide source code comments to describe at least the arguments, return value and effect of these functions. 

IMO, it is very important to provide enough clues in the include file and make it as easy as possible to use this interface. 

Secondly, each of the intended members of the public interface should be documented in a manual describing the function arguments, return value and effect. 

Preferably this should add value to the source code comments and also include an example of the usage, as well as some recommendations (a scenario) illustrating the purpose of the function (rather than just its effect).

Thank you for a problem report.

see:

http://forge.mysql.com/wiki/MySQL_Internals_Support_for_Plug-Ins

This bug has been promoted to a WorkLog item, and is now part of: 

http://forge.mysql.com/worklog/task.php?id=5228

is there a reason for WL#5228 to be private ?

Actually it's marked public, but it certainly isn't showing on the Forge, so I will check why this isn't showing.

yuck.
I've vaguely remember that forge has a hard-coded of WL categories to show.
Perhaps WL#5228 is in the other category ?