improve code docs in api2

Note: API methos should be declared pub, so that they show up in the generated docu.

src/api2/access.rs

@@ -1,3 +1,5 @@
+//! Access control (Users, Permissions and Authentication)
+
 use anyhow::{bail, format_err, Error};
 
 use serde_json::{json, Value};
@@ -177,7 +179,7 @@ fn authenticate_2nd(
 /// Create or verify authentication ticket.
 ///
 /// Returns: An authentication ticket with additional infos.
-fn create_ticket(
+pub fn create_ticket(
     username: Userid,
     password: String,
     path: Option<String>,
@@ -253,7 +255,7 @@ fn create_ticket(
 ///
 /// Each user is allowed to change his own password. Superuser
 /// can change all passwords.
-fn change_password(
+pub fn change_password(
     userid: Userid,
     password: String,
     rpcenv: &mut dyn RpcEnvironment,

src/api2/access/acl.rs

@@ -1,5 +1,6 @@
+//! Manage Access Control Lists
+
 use anyhow::{bail, Error};
-use ::serde::{Deserialize, Serialize};
 
 use proxmox::api::{api, Router, RpcEnvironment, Permission};
 use proxmox::tools::fs::open_file_locked;
@@ -9,36 +10,6 @@ use crate::config::acl;
 use crate::config::acl::{Role, PRIV_SYS_AUDIT, PRIV_PERMISSIONS_MODIFY};
 use crate::config::cached_user_info::CachedUserInfo;
 
-#[api(
-    properties: {
-        propagate: {
-            schema: ACL_PROPAGATE_SCHEMA,
-        },
- 	path: {
-            schema: ACL_PATH_SCHEMA,
-        },
-        ugid_type: {
-            schema: ACL_UGID_TYPE_SCHEMA,
-        },
-	ugid: {
-            type: String,
-            description: "User or Group ID.",
-        },
-	roleid: {
-            type: Role,
-        }
-    }
-)]
-#[derive(Serialize, Deserialize)]
-/// ACL list entry.
-pub struct AclListItem {
-    path: String,
-    ugid: String,
-    ugid_type: String,
-    propagate: bool,
-    roleid: String,
-}
-
 fn extract_acl_node_data(
     node: &acl::AclTreeNode,
     path: &str,

src/api2/access/domain.rs

@@ -1,3 +1,5 @@
+//! List Authentication domains/realms
+
 use anyhow::{Error};
 
 use serde_json::{json, Value};

src/api2/access/role.rs

@@ -1,3 +1,5 @@
+//! Manage Roles with privileges
+
 use anyhow::Error;
 
 use serde_json::{json, Value};

src/api2/access/tfa.rs

@@ -1,3 +1,5 @@
+//! Two Factor Authentication
+
 use anyhow::{bail, format_err, Error};
 use serde::{Deserialize, Serialize};
 

src/api2/access/user.rs

@@ -1,3 +1,5 @@
+//! User Management
+
 use anyhow::{bail, format_err, Error};
 use serde::{Serialize, Deserialize};
 use serde_json::{json, Value};

src/api2/admin.rs

@@ -1,3 +1,5 @@
+//! Backup Server Administration
+
 use proxmox::api::router::{Router, SubdirMap};
 use proxmox::list_subdirs_api_method;
 

src/api2/admin/datastore.rs

@@ -1,3 +1,5 @@
+//! Datastore Management
+
 use std::collections::HashSet;
 use std::ffi::OsStr;
 use std::os::unix::ffi::OsStrExt;
@@ -299,7 +301,7 @@ pub fn list_snapshot_files(
     },
 )]
 /// Delete backup snapshot.
-fn delete_snapshot(
+pub fn delete_snapshot(
     store: String,
     backup_type: String,
     backup_id: String,
@@ -795,7 +797,7 @@ pub const API_METHOD_PRUNE: ApiMethod = ApiMethod::new(
     true)
 );
 
-fn prune(
+pub fn prune(
     param: Value,
     _info: &ApiMethod,
     rpcenv: &mut dyn RpcEnvironment,
@@ -923,7 +925,7 @@ fn prune(
     },
 )]
 /// Start garbage collection.
-fn start_garbage_collection(
+pub fn start_garbage_collection(
     store: String,
     _info: &ApiMethod,
     rpcenv: &mut dyn RpcEnvironment,
@@ -983,7 +985,7 @@ pub fn garbage_collection_status(
     },
 )]
 /// Datastore list
-fn get_datastore_list(
+pub fn get_datastore_list(
     _param: Value,
     _info: &ApiMethod,
     rpcenv: &mut dyn RpcEnvironment,
@@ -1031,7 +1033,7 @@ pub const API_METHOD_DOWNLOAD_FILE: ApiMethod = ApiMethod::new(
     true)
 );
 
-fn download_file(
+pub fn download_file(
     _parts: Parts,
     _req_body: Body,
     param: Value,
@@ -1101,7 +1103,7 @@ pub const API_METHOD_DOWNLOAD_FILE_DECODED: ApiMethod = ApiMethod::new(
     true)
 );
 
-fn download_file_decoded(
+pub fn download_file_decoded(
     _parts: Parts,
     _req_body: Body,
     param: Value,
@@ -1215,7 +1217,7 @@ pub const API_METHOD_UPLOAD_BACKUP_LOG: ApiMethod = ApiMethod::new(
     &Permission::Privilege(&["datastore", "{store}"], PRIV_DATASTORE_BACKUP, false)
 );
 
-fn upload_backup_log(
+pub fn upload_backup_log(
     _parts: Parts,
     req_body: Body,
     param: Value,
@@ -1294,7 +1296,7 @@ fn upload_backup_log(
     },
 )]
 /// Get the entries of the given path of the catalog
-fn catalog(
+pub fn catalog(
     store: String,
     backup_type: String,
     backup_id: String,
@@ -1462,7 +1464,7 @@ pub const API_METHOD_PXAR_FILE_DOWNLOAD: ApiMethod = ApiMethod::new(
     true)
 );
 
-fn pxar_file_download(
+pub fn pxar_file_download(
     _parts: Parts,
     _req_body: Body,
     param: Value,
@@ -1599,7 +1601,7 @@ fn pxar_file_download(
     },
 )]
 /// Read datastore stats
-fn get_rrd_stats(
+pub fn get_rrd_stats(
     store: String,
     timeframe: RRDTimeFrameResolution,
     cf: RRDMode,
@@ -1641,7 +1643,7 @@ fn get_rrd_stats(
     },
 )]
 /// Get "notes" for a specific backup
-fn get_notes(
+pub fn get_notes(
     store: String,
     backup_type: String,
     backup_id: String,
@@ -1691,7 +1693,7 @@ fn get_notes(
     },
 )]
 /// Set "notes" for a specific backup
-fn set_notes(
+pub fn set_notes(
     store: String,
     backup_type: String,
     backup_id: String,
@@ -1736,7 +1738,7 @@ fn set_notes(
     },
 )]
 /// Change owner of a backup group
-fn set_backup_owner(
+pub fn set_backup_owner(
     store: String,
     backup_type: String,
     backup_id: String,

src/api2/admin/sync.rs

@@ -1,3 +1,5 @@
+//! Datastore Syncronization Job Management
+
 use anyhow::{bail, format_err, Error};
 use serde_json::Value;
 
@@ -110,7 +112,7 @@ pub fn list_sync_jobs(
     },
 )]
 /// Runs the sync jobs manually.
-fn run_sync_job(
+pub fn run_sync_job(
     id: String,
     _info: &ApiMethod,
     rpcenv: &mut dyn RpcEnvironment,

src/api2/admin/verify.rs

@@ -1,3 +1,5 @@
+//! Datastore Verify Job Management
+
 use anyhow::{format_err, Error};
 
 use proxmox::api::router::SubdirMap;
@@ -115,7 +117,7 @@ pub fn list_verification_jobs(
     },
 )]
 /// Runs a verification job manually.
-fn run_verification_job(
+pub fn run_verification_job(
     id: String,
     _info: &ApiMethod,
     rpcenv: &mut dyn RpcEnvironment,

src/api2/backup.rs

@@ -1,3 +1,5 @@
+//! Backup protocol (HTTP2 upgrade)
+
 use anyhow::{bail, format_err, Error};
 use futures::*;
 use hyper::header::{HeaderValue, UPGRADE};

src/api2/config.rs

@@ -1,3 +1,5 @@
+//! Backup Server Configuration
+
 use proxmox::api::router::{Router, SubdirMap};
 use proxmox::list_subdirs_api_method;
 

src/api2/node.rs

@@ -1,3 +1,5 @@
+//! Server/Node Configuration and Administration
+
 use std::net::TcpListener;
 use std::os::unix::io::AsRawFd;
 

src/api2/ping.rs

@@ -1,3 +1,5 @@
+//! Cheap check if the API daemon is online.
+
 use anyhow::{Error};
 use serde_json::{json, Value};
 
@@ -20,7 +22,7 @@ use proxmox::api::{api, Router, Permission};
     }
 )]
 /// Dummy method which replies with `{ "pong": True }`
-fn ping() -> Result<Value, Error> {
+pub fn ping() -> Result<Value, Error> {
     Ok(json!({
         "pong": true,
     }))

src/api2/reader.rs

@@ -1,3 +1,5 @@
+//! Backup reader/restore protocol (HTTP2 upgrade)
+
 use anyhow::{bail, format_err, Error};
 use futures::*;
 use hyper::header::{self, HeaderValue, UPGRADE};

src/api2/status.rs

@@ -1,3 +1,5 @@
+//! Datastote status
+
 use proxmox::list_subdirs_api_method;
 
 use anyhow::{Error};
@@ -75,7 +77,7 @@ use crate::config::acl::{
     },
 )]
 /// List Datastore usages and estimates
-fn datastore_status(
+pub fn datastore_status(
     _param: Value,
     _info: &ApiMethod,
     rpcenv: &mut dyn RpcEnvironment,

src/api2/tape/mod.rs

@@ -1,3 +1,5 @@
+//! Tape Backup Management
+
 use proxmox::api::router::SubdirMap;
 use proxmox::api::Router;
 use proxmox::list_subdirs_api_method;

src/api2/types/mod.rs

@@ -1,3 +1,5 @@
+//! API Type Definitions
+
 use anyhow::bail;
 use serde::{Deserialize, Serialize};
 
@@ -5,8 +7,15 @@ use proxmox::api::{api, schema::*};
 use proxmox::const_regex;
 use proxmox::{IPRE, IPRE_BRACKET, IPV4RE, IPV6RE, IPV4OCTET, IPV6H16, IPV6LS32};
 
-use crate::backup::{CryptMode, Fingerprint, BACKUP_ID_REGEX};
-use crate::server::UPID;
+use crate::{
+    backup::{
+        CryptMode,
+        Fingerprint,
+        BACKUP_ID_REGEX,
+    },
+    server::UPID,
+    config::acl::Role,
+};
 
 #[macro_use]
 mod macros;
@@ -282,6 +291,36 @@ pub const ACL_UGID_TYPE_SCHEMA: Schema = StringSchema::new(
         EnumEntry::new("group", "Group")]))
     .schema();
 
+#[api(
+    properties: {
+        propagate: {
+            schema: ACL_PROPAGATE_SCHEMA,
+        },
+	path: {
+            schema: ACL_PATH_SCHEMA,
+        },
+        ugid_type: {
+            schema: ACL_UGID_TYPE_SCHEMA,
+        },
+	ugid: {
+            type: String,
+            description: "User or Group ID.",
+        },
+	roleid: {
+            type: Role,
+        }
+    }
+)]
+#[derive(Serialize, Deserialize)]
+/// ACL list entry.
+pub struct AclListItem {
+    pub path: String,
+    pub ugid: String,
+    pub ugid_type: String,
+    pub propagate: bool,
+    pub roleid: String,
+}
+
 pub const BACKUP_ARCHIVE_NAME_SCHEMA: Schema =
     StringSchema::new("Backup archive name.")
     .format(&PROXMOX_SAFE_ID_FORMAT)

src/api2/version.rs

@@ -1,3 +1,5 @@
+//! Version information
+
 use anyhow::{Error};
 use serde_json::{json, Value};