doc: add some doc in highlevel

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.
+/// The sketchpad of complete [Program].
-///
+/// 
-/// We will create a Schema first, fill some properties, add file extensions,
+/// In suggested usage, we will create a [Schema] first, 
-/// then convert it into immutable Program for following using.
+/// 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 {
         }
     }
 
-    ///
+    /// Add a file extension to the schema.
-    ///
+    /// 
-    /// The passed `ext` string should be without leading dot `.`.
+    /// 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, ParseProgramError> {
         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<Self, ParseProgramError> {
         // Extract file name part and directory name part respectively.
         let schema_path = Path::new(&schema.path);