proxmox-sys: improve dev docs

And move WorkerTaskContext to top level.

Signed-off-by: Dietmar Maurer <dietmar@proxmox.com>

proxmox-sys/src/command.rs

@@ -1,3 +1,5 @@
+//! Helpers to run a [Command] and check status code
+
 use std::process::{Output, Command};
 
 use anyhow::{bail, format_err, Error};

proxmox-sys/src/crypt.rs

@@ -1,3 +1,5 @@
+//! Rust bindings for libcrypt
+
 use std::ffi::CStr;
 
 use anyhow::{bail, Error};
@@ -18,6 +20,7 @@ struct crypt_data {
     internal: [libc::c_char; CRYPT_DATA_INTERNAL_SIZE],
 }
 
+/// Encrypt a pasword - see man crypt(3)
 pub fn crypt(password: &[u8], salt: &[u8]) -> Result<String, Error> {
     #[link(name = "crypt")]
     extern "C" {
@@ -51,6 +54,7 @@ pub fn crypt(password: &[u8], salt: &[u8]) -> Result<String, Error> {
     Ok(String::from(res.to_str()?))
 }
 
+/// Encrypt a pasword using sha256 hashing method
 pub fn encrypt_pw(password: &str) -> Result<String, Error> {
 
     let salt = crate::linux::random_data(8)?;
@@ -59,6 +63,7 @@ pub fn encrypt_pw(password: &str) -> Result<String, Error> {
     crypt(password.as_bytes(), salt.as_bytes())
 }
 
+/// Verify if an encrypted password matches
 pub fn verify_crypt_pw(password: &str, enc_password: &str) -> Result<(), Error> {
     let verify = crypt(password.as_bytes(), enc_password.as_bytes())?;
     if verify != enc_password {

proxmox-sys/src/fs/fsx_attr.rs

@@ -16,6 +16,7 @@ nix::ioctl_write_ptr!(fs_ioc_fssetxattr, b'X', 32, FSXAttr);
 
 #[repr(C)]
 #[derive(Debug)]
+/// Rust bindings for struct fsxattr (fsgetxattr, fssetxattr)
 pub struct FSXAttr {
     pub fsx_xflags: u32,
     pub fsx_extsize: u32,

proxmox-sys/src/fs/mod.rs

@@ -39,7 +39,7 @@ pub fn fchown(fd: RawFd, owner: Option<Uid>, group: Option<Gid>) -> Result<(), E
     Ok(())
 }
 
-// FIXME: Consider using derive-builder!
+/// Define permissions, owner and group when creating files/dirs
 #[derive(Clone, Default)]
 pub struct CreateOptions {
     perm: Option<stat::Mode>,

proxmox-sys/src/lib.rs

@@ -8,4 +8,6 @@ pub mod logrotate;
 pub mod macros;
 pub mod mmap;
 pub mod process_locker;
-pub mod worker_task_context;
+
+mod worker_task_context;
+pub use worker_task_context::*;

proxmox-sys/src/logrotate.rs

@@ -1,3 +1,5 @@
+//! Log rotation helper
+
 use std::path::{Path, PathBuf};
 use std::fs::{File, rename};
 use std::os::unix::io::{FromRawFd, IntoRawFd};

proxmox-sys/src/worker_task_context.rs

@@ -56,6 +56,7 @@ impl<T: WorkerTaskContext + ?Sized> WorkerTaskContext for std::sync::Arc<T> {
     }
 }
 
+/// Log an error to a [WorkerTaskContext]
 #[macro_export]
 macro_rules! task_error {
     ($task:expr, $($fmt:tt)+) => {{
@@ -63,6 +64,7 @@ macro_rules! task_error {
     }};
 }
 
+/// Log a warning to a [WorkerTaskContext]
 #[macro_export]
 macro_rules! task_warn {
     ($task:expr, $($fmt:tt)+) => {{
@@ -70,6 +72,7 @@ macro_rules! task_warn {
     }};
 }
 
+/// Log a message to a [WorkerTaskContext]
 #[macro_export]
 macro_rules! task_log {
     ($task:expr, $($fmt:tt)+) => {{
@@ -77,6 +80,7 @@ macro_rules! task_log {
     }};
 }
 
+/// Log a debug message to a [WorkerTaskContext]
 #[macro_export]
 macro_rules! task_debug {
     ($task:expr, $($fmt:tt)+) => {{
@@ -84,6 +88,7 @@ macro_rules! task_debug {
     }};
 }
 
+/// Log a trace message to a [WorkerTaskContext]
 #[macro_export]
 macro_rules! task_trace {
     ($task:expr, $($fmt:tt)+) => {{