diff --git a/wfassoc/src/highlevel.rs b/wfassoc/src/highlevel.rs index 3d94a97..7e30ecd 100644 --- a/wfassoc/src/highlevel.rs +++ b/wfassoc/src/highlevel.rs @@ -11,14 +11,14 @@ pub use lowlevel::{Scope, View}; // region: Error Type -/// Error occurs when operating with `Schema`. +/// Error occurs when operating with [Schema]. #[derive(Debug, TeError)] pub enum SchemaError { #[error("duplicate key: {0}")] DuplicateKey(String), } -/// Error occurs when trying converting `Schema` into `Program`. +/// Error occurs when trying converting [Schema] into [Program]. #[derive(Debug, TeError)] pub enum ParseProgramError { #[error("{0}")] @@ -43,7 +43,7 @@ pub enum ParseProgramError { BadIdentifier, } -/// Error occurs when operating with `Program`. +/// Error occurs when operating with [Program]. #[derive(Debug, TeError)] pub enum ProgramError {} @@ -53,10 +53,12 @@ pub enum ProgramError {} // region: Schema Body -/// Schema is the sketchpad of complete Program. -/// -/// We will create a Schema first, fill some properties, add file extensions, -/// then convert it into immutable Program for following using. +/// The sketchpad of complete [Program]. +/// +/// In suggested usage, we will create a [Schema] first, +/// fill some essential and optional properties, +/// then add file extensions which we need. +/// And finally convert it into immutable [Program] for formal using. #[derive(Debug)] pub struct Schema { identifier: String, @@ -89,10 +91,16 @@ impl Schema { } } + /// Set the identifier of the schema. + /// + /// The identifier is used to build ProgId. + /// So it should starts with an ASCII letter and followed by zero or more ASCII letters, digits, underline and hyphen. + /// And it should not be empty. pub fn set_identifier(&mut self, identifier: &str) -> () { self.identifier = identifier.to_string(); } + /// Set the absolute path to the executable file. pub fn set_path(&mut self, exe_path: &str) -> () { self.path = exe_path.to_string(); } @@ -134,9 +142,9 @@ impl Schema { } } - /// - /// - /// The passed `ext` string should be without leading dot `.`. + /// Add a file extension to the schema. + /// + /// The parameter `ext` is the file extension without leading dot `.`. pub fn add_ext( &mut self, ext: &str, @@ -153,6 +161,9 @@ impl Schema { } } + /// Try converting [Schema] into [Program]. + /// + /// This is equivalent to [Program::new]. pub fn into_program(self) -> Result { Program::new(self) } @@ -287,7 +298,11 @@ impl Program { Ok(losse_progid) } - /// Try creating Program from Schema. + /// Try converting [Schema] into [Program]. + /// + /// During this process, some checks will be performed to ensure the validity of the data. + /// For example, the reference to icon, name, or behavior must exist in their respective dictionaries. + /// The identifier must be suit for building ProgId. pub fn new(schema: Schema) -> Result { // Extract file name part and directory name part respectively. let schema_path = Path::new(&schema.path);