Skip to content

Commit c72c7c2

Browse files
petehayes102petehayes102
committed
Major update of rustdoc comments to improve readability of generated documentation
1 parent 4709930 commit c72c7c2

File tree

13 files changed

+385
-424
lines changed

13 files changed

+385
-424
lines changed

‎src/command/mod.rs

Lines changed: 36 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -6,44 +6,44 @@
66
// https://www.tldrlegal.com/l/mpl-2.0>. This file may not be copied,
77
// modified, or distributed except according to those terms.
88

9-
//! The shell command primitive for running commands on a managed
10-
//! host.
11-
//!
12-
//! # Examples
13-
//!
14-
//! Initialise a new Host using your managed host's IP address and
15-
//! port number:
16-
//!
17-
//! ```no_run
18-
//! # use inapi::Host;
19-
#![cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
20-
#![cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
21-
#![cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
22-
//! ```
23-
//!
24-
//! Now run your command and get the result:
25-
//!
26-
//! ```no_run
27-
//! # use inapi::{Command, Host};
28-
#![cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
29-
#![cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
30-
#![cfg_attr(feature = "remote-run", doc = "# let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
31-
//! let cmd = Command::new("whoami");
32-
//! let result = cmd.exec(&mut host).unwrap();
33-
//! println!("Exit: {}, Stdout: {}, Stderr: {}", result.exit_code, result.stdout, result.stderr);
34-
//! ```
35-
//!
36-
//! If all goes well, this will output:
37-
//!
38-
//! > Exit: 0, Stdout: <agent_runtime_user>, Stderr:
9+
//! Command primitive.
3910
4011
pub mod ffi;
4112

4213
use error::Result;
4314
use host::Host;
4415
use target::Target;
4516

46-
/// Reusable container for sending commands to managed hosts.
17+
/// Primitive for running shell commands.
18+
///
19+
/// On your host, commands are passed to `/bin/sh -c` to be executed.
20+
///
21+
///# Examples
22+
///
23+
/// Initialise a new Host:
24+
///
25+
/// ```no_run
26+
/// # use inapi::Host;
27+
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
28+
#[cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
29+
#[cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
30+
/// ```
31+
///
32+
/// Now run your command and get the result:
33+
///
34+
/// ```no_run
35+
/// # use inapi::{Command, Host};
36+
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
37+
#[cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
38+
#[cfg_attr(feature = "remote-run", doc = "# let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
39+
///let cmd = Command::new("whoami");
40+
///let result = cmd.exec(&mut host).unwrap();
41+
///println!("I am running as {}", result.stdout);
42+
/// ```
43+
///
44+
/// If all goes well, this will output something like:
45+
///
46+
///> I am running as root
4747
pub struct Command {
4848
/// The shell command
4949
cmd: String,
@@ -62,13 +62,6 @@ pub struct CommandResult {
6262

6363
impl Command {
6464
/// Create a new Command to represent your shell command.
65-
///
66-
/// # Examples
67-
///
68-
/// ```no_run
69-
/// # use inapi::Command;
70-
/// let cmd = Command::new("your shell command goes here");
71-
/// ```
7265
pub fn new(cmd: &str) -> Command {
7366
Command {
7467
cmd: cmd.to_string(),
@@ -81,21 +74,21 @@ impl Command {
8174
/// helpful if you are configuring a group of servers
8275
/// simultaneously.
8376
///
84-
/// # Examples
77+
///# Examples
8578
///
8679
/// ```no_run
87-
/// # use inapi::{Command, Host};
88-
/// let cmd = Command::new("whoami");
80+
///# use inapi::{Command, Host};
81+
///let cmd = Command::new("whoami");
8982
///
9083
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
9184
#[cfg_attr(feature = "local-run", doc = "let mut web1 = Host::local(path).unwrap();")]
9285
#[cfg_attr(feature = "remote-run", doc = "let mut web1 = Host::connect(\"data/hosts/web1.json\").unwrap();")]
93-
/// let w1_result = cmd.exec(&mut web1).unwrap();
86+
///let w1_result = cmd.exec(&mut web1).unwrap();
9487
///
9588
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
9689
#[cfg_attr(feature = "local-run", doc = "let mut web2 = Host::local(path).unwrap();")]
9790
#[cfg_attr(feature = "remote-run", doc = "let mut web2 = Host::connect(\"data/hosts/web2.json\").unwrap();")]
98-
/// let w2_result = cmd.exec(&mut web2).unwrap();
91+
///let w2_result = cmd.exec(&mut web2).unwrap();
9992
/// ```
10093
#[allow(unused_variables)]
10194
pub fn exec(&self, host: &mut Host) -> Result<CommandResult> {

‎src/directory/mod.rs

Lines changed: 26 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -6,32 +6,7 @@
66
// https://www.tldrlegal.com/l/mpl-2.0>. This file may not be copied,
77
// modified, or distributed except according to those terms.
88

9-
//! The primitive for managing directories on a managed host.
10-
//!
11-
//! # Examples
12-
//!
13-
//! Initialise a new Host using your managed host's IP address and
14-
//! port number:
15-
//!
16-
//! ```no_run
17-
//! # use inapi::Host;
18-
#![cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
19-
#![cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
20-
#![cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
21-
//! ```
22-
//!
23-
//! Now you can manage a directory on your managed host.
24-
//!
25-
//! ```no_run
26-
//! # use inapi::{Host, Directory, DirectoryOpts};
27-
#![cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
28-
#![cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
29-
#![cfg_attr(feature = "remote-run", doc = "# let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
30-
//! let dir = Directory::new(&mut host, "/path/to/dir").unwrap();
31-
//! dir.create(&mut host, Some(&vec![DirectoryOpts::DoRecursive])).unwrap();
32-
//! dir.set_owner(&mut host, "MyUser", "MyGroup").unwrap();
33-
//! dir.set_mode(&mut host, 755).unwrap();
34-
//! ```
9+
//! Directory primitive.
3510
3611
pub mod ffi;
3712

@@ -47,24 +22,38 @@ pub enum DirectoryOpts {
4722
DoRecursive,
4823
}
4924

50-
/// Container for operating on a directory.
25+
/// Primitive for managing directories.
26+
///
27+
///# Examples
28+
///
29+
/// Initialise a new Host:
30+
///
31+
/// ```no_run
32+
///# use inapi::Host;
33+
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
34+
#[cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
35+
#[cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
36+
/// ```
37+
///
38+
/// Now you can setup a directory on your managed host:
39+
///
40+
/// ```no_run
41+
///# use inapi::{Host, Directory, DirectoryOpts};
42+
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
43+
#[cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
44+
#[cfg_attr(feature = "remote-run", doc = "# let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
45+
///let dir = Directory::new(&mut host, "/path/to/dir").unwrap();
46+
///dir.create(&mut host, Some(&[DirectoryOpts::DoRecursive])).unwrap();
47+
///dir.set_owner(&mut host, "MyUser", "MyGroup").unwrap();
48+
///dir.set_mode(&mut host, 755).unwrap();
49+
/// ```
5150
pub struct Directory {
5251
/// Absolute path to directory on managed host
5352
path: PathBuf,
5453
}
5554

5655
impl Directory {
5756
/// Create a new Directory struct.
58-
///
59-
/// # Examples
60-
///
61-
/// ```no_run
62-
/// # use inapi::{Directory, Host};
63-
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
64-
#[cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
65-
#[cfg_attr(feature = "remote-run", doc = "# let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
66-
/// let directory = Directory::new(&mut host, "/path/to/dir");
67-
/// ```
6857
pub fn new<P: AsRef<Path>>(host: &mut Host, path: P) -> Result<Directory> {
6958
if ! try!(Target::directory_is_directory(host, path.as_ref())) {
7059
return Err(Error::Generic("Path is a file".to_string()));

‎src/error.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ pub extern "C" fn geterr() -> *const c_char {
3939
}
4040

4141
#[derive(Debug)]
42+
/// Global error type.
4243
pub enum Error {
4344
/// An error string returned from the host's Intecture Agent
4445
Agent(String),

‎src/file/mod.rs

Lines changed: 34 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,7 @@
66
// https://www.tldrlegal.com/l/mpl-2.0>. This file may not be copied,
77
// modified, or distributed except according to those terms.
88

9-
//! The primitive for managing files on a managed host.
10-
//!
11-
//! # Examples
12-
//!
13-
//! Initialise a new Host using your managed host's IP address and
14-
//! port number:
15-
//!
16-
//! ```no_run
17-
//! # use inapi::Host;
18-
#![cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
19-
#![cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
20-
#![cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
21-
//! ```
22-
//!
23-
//! Now you can manage a file on your managed host.
24-
//!
25-
//! ```no_run
26-
//! # use inapi::{Host, File, FileOptions};
27-
#![cfg_attr(feature = "local-run", doc = "# let path: Option<String> = None;")]
28-
#![cfg_attr(feature = "local-run", doc = "# let mut host = Host::local(path).unwrap();")]
29-
#![cfg_attr(feature = "remote-run", doc = "# let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
30-
//! let file = File::new(&mut host, "/path/to/destination_file").unwrap();
31-
#![cfg_attr(feature = "remote-run", doc = " file.upload(&mut host, \"/path/to/local_file\", None);")]
32-
//! file.set_owner(&mut host, "MyUser", "MyGroup").unwrap();
33-
//! file.set_mode(&mut host, 644).unwrap();
34-
//!
35-
#![cfg_attr(feature = "remote-run", doc = " // Now let's upload another file and backup the original")]
36-
#![cfg_attr(feature = "remote-run", doc = " file.upload(&mut host, \"/path/to/new_file\", Some(&vec![FileOptions::BackupExisting(\"_bk\".to_string())])).unwrap();")]
37-
#![cfg_attr(feature = "remote-run", doc = "")]
38-
#![cfg_attr(feature = "remote-run", doc = " // Your remote path now has two entries:")]
39-
#![cfg_attr(feature = "remote-run", doc = " // \"/path/to/destination_file\" and \"/path/to/destination_file_bk\"")]
40-
//! ```
9+
//! File primitive.
4110
4211
pub mod ffi;
4312

@@ -66,24 +35,46 @@ pub struct FileOwner {
6635
pub group_gid: u64,
6736
}
6837

69-
/// Container for operating on a file.
38+
/// Primitive for managing files.
39+
///
40+
///# Examples
41+
///
42+
/// Initialise a new Host:
43+
///
44+
/// ```no_run
45+
/// # use inapi::Host;
46+
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
47+
#[cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
48+
#[cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
49+
/// ```
50+
///
51+
/// Now you can manage a file on your managed host.
52+
///
53+
/// ```no_run
54+
/// # use inapi::{Host, File, FileOptions};
55+
#[cfg_attr(feature = "local-run", doc = "# let path: Option<String> = None;")]
56+
#[cfg_attr(feature = "local-run", doc = "# let mut host = Host::local(path).unwrap();")]
57+
#[cfg_attr(feature = "remote-run", doc = "# let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
58+
///let file = File::new(&mut host, "/path/to/destination_file").unwrap();
59+
#[cfg_attr(feature = "remote-run", doc = "file.upload(&mut host, \"/path/to/local_file\", None);")]
60+
///file.set_owner(&mut host, "MyUser", "MyGroup").unwrap();
61+
///file.set_mode(&mut host, 644).unwrap();
62+
///
63+
#[cfg_attr(feature = "remote-run", doc = "// Now let's upload another file and backup the original")]
64+
#[cfg_attr(feature = "remote-run", doc = "file.upload(&mut host, \"/path/to/new_file\", Some(&[
65+
FileOptions::BackupExisting(\"_bk\".to_string())
66+
])).unwrap();")]
67+
#[cfg_attr(feature = "remote-run", doc = "")]
68+
#[cfg_attr(feature = "remote-run", doc = "// Your remote path now has two entries:")]
69+
#[cfg_attr(feature = "remote-run", doc = "// \"/path/to/destination_file\" and \"/path/to/destination_file_bk\"")]
70+
/// ```
7071
pub struct File {
7172
/// Absolute path to file on managed host
7273
path: PathBuf,
7374
}
7475

7576
impl File {
7677
/// Create a new File struct.
77-
///
78-
/// # Examples
79-
///
80-
/// ```no_run
81-
/// # use inapi::{File, Host};
82-
#[cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
83-
#[cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
84-
#[cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
85-
/// let file = File::new(&mut host, "/path/to/file");
86-
/// ```
8778
pub fn new<P: AsRef<Path>>(host: &mut Host, path: P) -> Result<File> {
8879
if ! try!(Target::file_is_file(host, path.as_ref())) {
8980
return Err(Error::Generic("Path is a directory".to_string()));

‎src/host/mod.rs

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,7 @@
66
// https://www.tldrlegal.com/l/mpl-2.0>. This file may not be copied,
77
// modified, or distributed except according to those terms.
88

9-
//! The host wrapper for communicating with a managed host.
10-
//!
11-
//! # Examples
12-
//!
13-
//! ```no_run
14-
//! # use inapi::{Command, Host};
15-
#![cfg_attr(feature = "local-run", doc = "let path: Option<String> = None;")]
16-
#![cfg_attr(feature = "local-run", doc = "let mut host = Host::local(path).unwrap();")]
17-
#![cfg_attr(feature = "remote-run", doc = "let mut host = Host::connect(\"hosts/myhost.json\").unwrap();")]
18-
//!
19-
//! let cmd = Command::new("whoami");
20-
//! let result = cmd.exec(&mut host).unwrap();
21-
//! ```
9+
//! Host primitive.
2210
2311
#[macro_use]
2412
pub mod data;
@@ -43,14 +31,35 @@ use std::rc::Rc;
4331
use zfilexfer;
4432

4533
#[cfg(feature = "local-run")]
46-
/// Representation of a managed host.
34+
/// Primitive for communicating with a managed host.
35+
///
36+
///# Examples
37+
///
38+
/// ```no_run
39+
/// # use inapi::{Command, Host};
40+
///let path: Option<String> = None;
41+
///let mut host = Host::local(path).unwrap();
42+
///
43+
///let cmd = Command::new("whoami");
44+
///let result = cmd.exec(&mut host).unwrap();
45+
/// ```
4746
pub struct Host {
4847
/// Data for host, comprising data files and telemetry
4948
data: Rc<Value>,
5049
}
5150

5251
#[cfg(feature = "remote-run")]
53-
/// Representation of a managed host.
52+
/// Primitive for communicating with a managed host.
53+
///
54+
///# Examples
55+
///
56+
/// ```no_run
57+
/// # use inapi::{Command, Host};
58+
///let mut host = Host::connect("hosts/myhost.json").unwrap();
59+
///
60+
///let cmd = Command::new("whoami");
61+
///let result = cmd.exec(&mut host).unwrap();
62+
/// ```
5463
pub struct Host {
5564
/// Hostname or IP of managed host
5665
pub hostname: String,
@@ -85,8 +94,10 @@ impl Host {
8594

8695
#[cfg(feature = "remote-run")]
8796
/// Create a new Host connected to the endpoint specified in the
88-
/// data file. This function expects to find the following keys
89-
/// in the root namespace: "hostname", "api_port", "file_port".
97+
/// data file.
98+
///
99+
/// This function expects to find the following keys in the root
100+
/// namespace: "hostname", "api_port", "file_port".
90101
pub fn connect<P: AsRef<Path>>(path: P) -> Result<Host> {
91102
let value = try!(data::open(path.as_ref()));
92103
let mut me = try!(Self::connect_endpoint(try!(needstr!(value => "/hostname")),

0 commit comments

Comments
 (0)