| 1.3. YCP Functions | ||
|---|---|---|
 | Chapter 1. YCP Module and Client Documentation |  |
| 1.3. YCP Functions | ||
|---|---|---|
| | Chapter 1. YCP Module and Client Documentation | |
The function header should describe all needed pieces of information about the function. Such as parameters, return value, function's textual description, examples, etc.
Example 1.12. Simple Example of Function Description
/**
* Returns number of just connected users to the server.
* You can filter these users by defining the filtering parameter.
*
* @param part_of_ip ("192.168.") that users are connected from
* @return integer number of connected users
*
* @see AnotherFunction()
*/
global integer GetCountOfConnectedUsers (string part_of_ip) {
...
}Function description tags:
@deprecated
@descr
@example
@param
@ref
@return
@short
@since
@stable
@struct
@unstable
Defines that the function has been deprecated. Additionaly defines another function as the replacement.
Complete description of the function. It might describe the environment or detailed behavior.
Example 1.15. Automatic description
/** * This first line is identified as @short * * This multi-line @descr (after a newline) is automatically * taken as the function description. * * Additionally, this multi-line text is automatically taken as another paragraph * of the function @descr (the number of paragraphs is unlimited). */
Block of examples of usage, they are as exported as they are written (like <pre> in HTML).
Example 1.16. Multiline @example block
@example
list <string> servers = GetListOfNSServers("example.com.");
boolean success = AddNewNSServer("ns4.example.com.", "example.com.");
Describes the parameter of the function. The order
of @param tags is significant.
Example 1.17. @param tag
/**
* Adds a new NS Server into list of domain NS servers.
*
* @param new_ns_server FQDN
* @param domain
* @return boolean successfull
*/
global boolean AddNewNSServer (string new_ns_server, string domain) {
...
return success;
}
Single-line version of @see tag.
Description of the return value.
Example 1.19. @return tag
/**
* Removes the NS Server from list of domain NS servers.
*
* @param ns_server FQDN
* @param domain
* @return boolean successfull
*/
global boolean RemoveNSServer (string ns_server, string domain) {
...
boolean success = true;
return success;
}Short single-line description of the function.
Example 1.21. Automatic description
/** * This first line is identified as @short * * This multi-line @descr (after a newline) is automatically * taken as the function description. */
See the @descr tag.
Since which version thix function exists. This is not a commonly used tag.
Defines that the function has a stable API and we don't plan to change it for years.
See tag @unstable.
This tag might changes the default value of the file's stability of the API (just for the current function).
This tag is used to represent the used data-structure closer. It's as represented as it's written (such as the <pre> HTML tag).
Example 1.24. @struct tag
@struct returns $[
// example.com.
"domain" : "domain name",
// list of NS servers assigned to the domain
"ns_servers" : [ "ns1", "ns2", ... ],
// map of MX servers $[ "server_name" : priority ]
"mx_servers" : $[ "mx1" : 10, "mx2" : 5 ],
]| |  | |
| 1.2. YCP File Header |  | 1.4. YCP Variables |