-
Documentation task
-
Resolution: Fixed
-
Trivial
-
None
-
Sprint 101 (Jun 2023), Sprint 102 (Jul 2023)
-
0.5
Loadable plugins page provides an example of plugin code with comments, here is an excerpt from it:
// This is the main function, it is required to compile the plugin. // By default the function implements our packages to handle the plugin creation and execution. func main() { h, err := container.NewHandler(impl.Name()) if err != nil { panic(fmt.Sprintf("failed to create plugin handler %s", err.Error())) } impl.Logger = &h err = h.Execute() if err != nil { panic(fmt.Sprintf("failed to execute plugin handler %s", err.Error())) } }
I have a couple of issues understanding the following part:
By default the function implements our packages to handle the plugin creation and execution.
There are several issues:
- "by default" means "in absence of any opposing action". An absence of what is meant in this context? I can only guess author's intent, but "usually the function implements ..." or "typically the function implements ..." or "at a minimum function implements ..." would make more sense.
- "function implements our packages" is a weird thing to say. Package is a bigger chunk of source code defining functions, classes, types and whatnot. It can theoretically consist of a single function, but even then it would be strange to say that "function implements package". And it is never correct to say that "function implements packages" in plural form. I would guess that something like "function asks our packages to handle ..." or "function instructs our packages to handle ..." was meant instead.
- It says "our packages" about packages developed and maintained by Zabbix in a piece of documentation that is essentially a tutorial guiding user through a process of creating a plugin. A few lines above another code comment says "Register our metric ..." referring to a metric, collectively implemented by the author and the reader of documentation. I would suggest to fix this inconsistent use of "our" by saying "Zabbix packages" instead of "our packages".