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 13:57	Modified:	18 Jan 15:20
Reporter:	Roland Bouman
Status:	Closed
Category:	Server: Docs	Severity:	S3 (Non-critical)
Version:	5.1.22-rc	OS:	Any
Assigned to:	MC Brown	Target Version:
Triage:	Triaged: D4 (Minor)

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 ?