From 4b8ddb5de3e2d7123c17dc600bce97c55683f029 Mon Sep 17 00:00:00 2001 From: The Noah Date: Thu, 14 Feb 2019 20:20:47 -0600 Subject: [PATCH 1/4] Add documentation for some API server functions --- .../developer/bzfs_api_functions/bz_APIVersion.md | 4 ++-- _documentation/developer/bzfs_api_functions/bz_MD5.md | 6 +++--- .../developer/bzfs_api_functions/bz_getProtocolVersion.md | 4 ++-- .../developer/bzfs_api_functions/bz_getServerVersion.md | 4 ++-- .../developer/bzfs_api_functions/bz_loadPlugin.md | 8 ++++---- .../developer/bzfs_api_functions/bz_unloadPlugin.md | 6 +++--- 6 files changed, 16 insertions(+), 16 deletions(-) diff --git a/_documentation/developer/bzfs_api_functions/bz_APIVersion.md b/_documentation/developer/bzfs_api_functions/bz_APIVersion.md index b1cf432..bf58615 100644 --- a/_documentation/developer/bzfs_api_functions/bz_APIVersion.md +++ b/_documentation/developer/bzfs_api_functions/bz_APIVersion.md @@ -5,7 +5,7 @@ signatures: - [] returns: dataType: int - description: ~ + description: BZAPI version. --- -This function needs a description. Please feel free to contribute a description to this function. +Useful for checking API version requirements a plug-in may have. diff --git a/_documentation/developer/bzfs_api_functions/bz_MD5.md b/_documentation/developer/bzfs_api_functions/bz_MD5.md index d01b843..00e4f9c 100644 --- a/_documentation/developer/bzfs_api_functions/bz_MD5.md +++ b/_documentation/developer/bzfs_api_functions/bz_MD5.md @@ -4,11 +4,11 @@ category: String Operations signatures: - - dataType: const char* name: str - description: ~ + description: String to be hashed. default: ~ returns: dataType: const char* - description: ~ + description: The MD5 hash of `str`. --- -This function needs a description. Please feel free to contribute a description to this function. +Creates an MD5 hash of the `str` argument provided. diff --git a/_documentation/developer/bzfs_api_functions/bz_getProtocolVersion.md b/_documentation/developer/bzfs_api_functions/bz_getProtocolVersion.md index 5b5b26c..f29247a 100644 --- a/_documentation/developer/bzfs_api_functions/bz_getProtocolVersion.md +++ b/_documentation/developer/bzfs_api_functions/bz_getProtocolVersion.md @@ -5,7 +5,7 @@ signatures: - [] returns: dataType: const char* - description: ~ + description: The protocol version. --- -This function needs a description. Please feel free to contribute a description to this function. +Returns BZFlag protocol version. Example: `0221`. diff --git a/_documentation/developer/bzfs_api_functions/bz_getServerVersion.md b/_documentation/developer/bzfs_api_functions/bz_getServerVersion.md index 1ca5c32..2ad5f39 100644 --- a/_documentation/developer/bzfs_api_functions/bz_getServerVersion.md +++ b/_documentation/developer/bzfs_api_functions/bz_getServerVersion.md @@ -5,7 +5,7 @@ signatures: - [] returns: dataType: const char* - description: ~ + description: The protocol version with "BZFS" added to the front. --- -This function needs a description. Please feel free to contribute a description to this function. +Returns the server's protocol version. Example: `BZFS0221`. diff --git a/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md b/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md index f5ee3b9..1a9d0fe 100644 --- a/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md +++ b/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md @@ -4,15 +4,15 @@ category: Plug-in Management signatures: - - dataType: const char* name: path - description: ~ + description: Path to the plug-in to be loaded. default: ~ - dataType: const char* name: params - description: ~ + description: Parameters to be passed to the plug-in. default: ~ returns: dataType: bool - description: ~ + description: `true` if it succeeded, otherwise `false`. --- -This function needs a description. Please feel free to contribute a description to this function. +Loads a plug-in based on arguments provided. Returns `true` if successfully loaded, `false` if not. diff --git a/_documentation/developer/bzfs_api_functions/bz_unloadPlugin.md b/_documentation/developer/bzfs_api_functions/bz_unloadPlugin.md index 3af2b5d..38f0813 100644 --- a/_documentation/developer/bzfs_api_functions/bz_unloadPlugin.md +++ b/_documentation/developer/bzfs_api_functions/bz_unloadPlugin.md @@ -4,11 +4,11 @@ category: Plug-in Management signatures: - - dataType: const char* name: path - description: ~ + description: Path to the plug-in to be unloaded. default: ~ returns: dataType: bool - description: ~ + description: `true` if it succeeded, `false` if it didn't. --- -This function needs a description. Please feel free to contribute a description to this function. +Unloads a plug-in based on arguments provided. From a7dd58488489ef89c01b745b1027df155b56ed7f Mon Sep 17 00:00:00 2001 From: Vladimir Jimenez Date: Sat, 16 Feb 2019 09:25:47 -0600 Subject: [PATCH 2/4] Update _documentation/developer/bzfs_api_functions/bz_loadPlugin.md Co-Authored-By: The-Noah --- _documentation/developer/bzfs_api_functions/bz_loadPlugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md b/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md index 1a9d0fe..2822c99 100644 --- a/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md +++ b/_documentation/developer/bzfs_api_functions/bz_loadPlugin.md @@ -15,4 +15,4 @@ returns: description: `true` if it succeeded, otherwise `false`. --- -Loads a plug-in based on arguments provided. Returns `true` if successfully loaded, `false` if not. +Loads a plug-in based on arguments provided. From 7d516267b1e78f62f59b8865cb88f5f9631bee43 Mon Sep 17 00:00:00 2001 From: The Noah Date: Sat, 16 Feb 2019 15:43:43 -0600 Subject: [PATCH 3/4] Update bz_APIVersion.md --- _documentation/developer/bzfs_api_functions/bz_APIVersion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_documentation/developer/bzfs_api_functions/bz_APIVersion.md b/_documentation/developer/bzfs_api_functions/bz_APIVersion.md index bf58615..5659504 100644 --- a/_documentation/developer/bzfs_api_functions/bz_APIVersion.md +++ b/_documentation/developer/bzfs_api_functions/bz_APIVersion.md @@ -8,4 +8,4 @@ returns: description: BZAPI version. --- -Useful for checking API version requirements a plug-in may have. +Returns the BZAPI version (`BZ_API_VERSION`). It is used by bzfs so it can safely fail to load plug-ins compiled with an older version of bzfs. From 31bbabcbacb2ba645fd1e7370882c6d53895fff2 Mon Sep 17 00:00:00 2001 From: Vladimir Jimenez Date: Sat, 16 Feb 2019 21:19:09 -0600 Subject: [PATCH 4/4] Update _documentation/developer/bzfs_api_functions/bz_APIVersion.md Co-Authored-By: The-Noah --- _documentation/developer/bzfs_api_functions/bz_APIVersion.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_documentation/developer/bzfs_api_functions/bz_APIVersion.md b/_documentation/developer/bzfs_api_functions/bz_APIVersion.md index 5659504..b23eeae 100644 --- a/_documentation/developer/bzfs_api_functions/bz_APIVersion.md +++ b/_documentation/developer/bzfs_api_functions/bz_APIVersion.md @@ -8,4 +8,6 @@ returns: description: BZAPI version. --- -Returns the BZAPI version (`BZ_API_VERSION`). It is used by bzfs so it can safely fail to load plug-ins compiled with an older version of bzfs. +The internal API version is used by bzfs so it can safely fail to load plugins that were compiled with older versions of bzfs that had a different API version. This value is only changed during protocol breaks or when something changes in the API such as the signature for an existing function or properties of API objects. + +Most plug-ins won't have the need to make use of this information.