Document the code (#196)

Author: Luni-4

rust-code-analysis-cli/src/main.rs

@@ -112,15 +112,14 @@ fn act_on_file(language: Option<LANG>, path: PathBuf, cfg: &Config) -> std::io::
         action::<Function>(&language, source, &path, pr, cfg)
     } else if !cfg.find_filter.is_empty() {
         let cfg = FindCfg {
-            path: Some(path.clone()),
+            path: path.clone(),
             filters: cfg.find_filter.clone(),
             line_start: cfg.line_start,
             line_end: cfg.line_end,
         };
         action::<Find>(&language, source, &path, pr, cfg)
     } else if cfg.count_lock.is_some() {
         let cfg = CountCfg {
-            path: Some(path.clone()),
             filters: cfg.count_filter.clone(),
             stats: cfg.count_lock.as_ref().unwrap().clone(),
         };

src/ast.rs

@@ -3,28 +3,52 @@ use serde::{Deserialize, Serialize};
 
 use crate::*;
 
+/// Start and end positions of a node in a code in terms of rows and columns.
+///
+/// The first and second fields represent the row and column associated to
+/// the start position of a node.
+///
+/// The third and fourth fields represent the row and column associated to
+/// the end position of a node.
 pub type Span = Option<(usize, usize, usize, usize)>;
 
+/// The payload of an `Ast` request.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct AstPayload {
+    /// The id associated to a request for an `AST`
     pub id: String,
+    /// The filename associated to a source code file
     pub file_name: String,
+    /// The code to be represented as an `AST`
     pub code: String,
+    /// If `true`, nodes representing comments are ignored
     pub comment: bool,
+    /// If `true`, the start and end positions of a node in a code
+    /// are considered
     pub span: bool,
 }
 
+/// The response of an `AST` request.
 #[derive(Debug, Serialize)]
 pub struct AstResponse {
+    /// The id associated to a request for an `AST`
     id: String,
+    /// The root node of an `AST`
+    ///
+    /// If `None`, an error has occurred
     root: Option<AstNode>,
 }
 
+/// Information on an `AST` node.
 #[derive(Debug)]
 pub struct AstNode {
+    /// The type of node
     pub r#type: &'static str,
+    /// The code associated to a node
     pub value: String,
+    /// The start and end positions of a node in a code
     pub span: Span,
+    /// The children of a node
     pub children: Vec<AstNode>,
 }
 
@@ -99,11 +123,18 @@ fn build<T: TSParserTrait>(parser: &T, span: bool, comment: bool) -> Option<AstN
     }
 }
 
-pub struct AstCallback {}
+pub struct AstCallback {
+    _guard: (),
+}
 
+/// Configuration options for retrieving the nodes of an `AST`.
 pub struct AstCfg {
+    /// The id associated to a request for an `AST`
     pub id: String,
+    /// If `true`, nodes representing comments are ignored
     pub comment: bool,
+    /// If `true`, the start and end positions of a node in a code
+    /// are considered
     pub span: bool,
 }
 

src/asttools.rs

@@ -16,6 +16,7 @@ pub fn get_parent<'a>(node: &'a Node<'a>, level: usize) -> Option<Node<'a>> {
     Some(node)
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! has_ancestors {
     ($node:expr, $( $typs:pat )|*, $( $typ:pat ),+) => {{

src/comment_rm.rs

@@ -7,6 +7,7 @@ use crate::traits::*;
 
 const CR: [u8; 8192] = [b'\n'; 8192];
 
+/// Removes comments from a code.
 pub fn rm_comments<T: TSParserTrait>(parser: &T) -> Option<Vec<u8>> {
     let node = parser.get_root();
     let mut stack = Vec::new();
@@ -59,12 +60,17 @@ fn remove_from_code(code: &[u8], mut spans: Vec<(usize, usize, usize)>) -> Vec<u
     new_code
 }
 
+/// Configuration options for removing comments from a code.
 pub struct CommentRmCfg {
+    /// If `true`, the modified code is saved on a file
     pub in_place: bool,
+    /// Path to output file
     pub path: PathBuf,
 }
 
-pub struct CommentRm {}
+pub struct CommentRm {
+    _guard: (),
+}
 
 impl Callback for CommentRm {
     type Res = std::io::Result<()>;

src/count.rs

@@ -2,11 +2,12 @@ extern crate num_format;
 
 use num_format::{Locale, ToFormattedString};
 use std::fmt;
-use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
 
 use crate::traits::*;
 
+/// Counts the types of nodes specified in the input slice
+/// and the number of nodes in a code.
 pub fn count<'a, T: TSParserTrait>(parser: &'a T, filters: &[String]) -> (usize, usize) {
     let filters = parser.get_filters(filters);
     let node = parser.get_root();
@@ -35,15 +36,21 @@ pub fn count<'a, T: TSParserTrait>(parser: &'a T, filters: &[String]) -> (usize,
     (good, total)
 }
 
+/// Configuration options for counting different
+/// types of nodes in a code.
 pub struct CountCfg {
-    pub path: Option<PathBuf>,
+    /// Types of nodes to count
     pub filters: Vec<String>,
+    /// Number of nodes of a certain type counted by each thread
     pub stats: Arc<Mutex<Count>>,
 }
 
+/// Count of different types of nodes in a code.
 #[derive(Debug, Default)]
 pub struct Count {
+    /// The number of specific types of nodes searched in a code
     pub good: usize,
+    /// The total number of nodes in a code
     pub total: usize,
 }
 

src/find.rs

@@ -4,6 +4,7 @@ use tree_sitter::Node;
 use crate::dump::*;
 use crate::traits::*;
 
+/// Finds the types of nodes specified in the input slice.
 pub fn find<'a, T: TSParserTrait>(parser: &'a T, filters: &[String]) -> Option<Vec<Node<'a>>> {
     let filters = parser.get_filters(filters);
     let node = parser.get_root();
@@ -34,14 +35,28 @@ pub fn find<'a, T: TSParserTrait>(parser: &'a T, filters: &[String]) -> Option<V
     Some(good)
 }
 
+/// Configuration options for finding different
+/// types of nodes in a code.
 pub struct FindCfg {
-    pub path: Option<PathBuf>,
+    /// Path to the file containing the code
+    pub path: PathBuf,
+    /// Types of nodes to find
     pub filters: Vec<String>,
+    /// The first line of code considered in the search
+    ///
+    /// If `None`, the search starts from the
+    /// first line of code in a file
     pub line_start: Option<usize>,
+    /// The end line of code considered in the search
+    ///
+    /// If `None`, the search ends at the
+    /// last line of code in a file
     pub line_end: Option<usize>,
 }
 
-pub struct Find {}
+pub struct Find {
+    _guard: (),
+}
 
 impl Callback for Find {
     type Res = std::io::Result<()>;
@@ -50,7 +65,7 @@ impl Callback for Find {
     fn call<T: TSParserTrait>(cfg: Self::Cfg, parser: &T) -> Self::Res {
         if let Some(good) = find(parser, &cfg.filters) {
             if !good.is_empty() {
-                println!("In file {:?}", cfg.path);
+                println!("In file {}", cfg.path.to_str().unwrap());
                 for node in good {
                     dump_node(parser.get_code(), &node, 1, cfg.line_start, cfg.line_end)?;
                 }

src/function.rs

@@ -7,14 +7,25 @@ use crate::traits::*;
 use crate::checker::Checker;
 use crate::getter::Getter;
 
+/// Function span data.
 #[derive(Debug, Serialize)]
 pub struct FunctionSpan {
+    /// The function name
     pub name: String,
+    /// The first line of a function
     pub start_line: usize,
+    /// The last line of a function
     pub end_line: usize,
+    /// If `true`, an error is occured in determining the span
+    /// of a function
     pub error: bool,
 }
 
+/// Detects the span of each function in a code.
+///
+/// Returns a vector containing the [`FunctionSpan`] of each function
+///
+/// [`FunctionSpan`]: struct.FunctionSpan.html
 pub fn function<T: TSParserTrait>(parser: &T) -> Vec<FunctionSpan> {
     let root = parser.get_root();
     let code = parser.get_code();
@@ -96,11 +107,16 @@ fn dump_spans(mut spans: Vec<FunctionSpan>, path: PathBuf) -> std::io::Result<()
     Ok(())
 }
 
+/// Configuration options for detecting the span of
+/// each function in a code.
 pub struct FunctionCfg {
+    /// Path to the file containing the code
     pub path: PathBuf,
 }
 
-pub struct Function {}
+pub struct Function {
+    _guard: (),
+}
 
 impl Callback for Function {
     type Res = std::io::Result<()>;

src/langs.rs

@@ -8,14 +8,16 @@ use crate::*;
 
 mk_langs!(
     // 1) Name for enum
-    // 2) Display name
-    // 3) Empty struct name to implement
-    // 4) Parser name
-    // 5) tree-sitter function to call to get a Language
-    // 6) file extensions
-    // 7) emacs modes
+    // 2) Language description
+    // 3) Display name
+    // 4) Empty struct name to implement
+    // 5) Parser name
+    // 6) tree-sitter function to call to get a Language
+    // 7) file extensions
+    // 8) emacs modes
     (
         Mozjs,
+        "The `Mozjs` language is variant of the `JavaScript` language",
         "javascript",
         MozjsCode,
         MozjsParser,
@@ -25,6 +27,7 @@ mk_langs!(
     ),
     (
         Javascript,
+        "The `JavaScript` language",
         "javascript",
         JavascriptCode,
         JavascriptParser,
@@ -34,16 +37,27 @@ mk_langs!(
     ),
     (
         Java,
+        "The `Java` language",
         "java",
         JavaCode,
         JavaParser,
         tree_sitter_java,
         [java],
         ["java"]
     ),
-    (Go, "go", GoCode, GoParser, tree_sitter_go, [go], ["go"]),
+    (
+        Go,
+        "The `Go` language",
+        "go",
+        GoCode,
+        GoParser,
+        tree_sitter_go,
+        [go],
+        ["go"]
+    ),
     (
         Html,
+        "The `HTML` language",
         "html",
         HtmlCode,
         HtmlParser,
@@ -53,6 +67,7 @@ mk_langs!(
     ),
     (
         CSharp,
+        "The `C#` language",
         "c#",
         CSharpCode,
         CSharpParser,
@@ -62,6 +77,7 @@ mk_langs!(
     ),
     (
         Rust,
+        "The `Rust` language",
         "rust",
         RustCode,
         RustParser,
@@ -71,6 +87,7 @@ mk_langs!(
     ),
     (
         Css,
+        "The `CSS` language",
         "css",
         CssCode,
         CssParser,
@@ -80,6 +97,7 @@ mk_langs!(
     ),
     (
         Cpp,
+        "The `C/C++` language",
         "c/c++",
         CppCode,
         CppParser,
@@ -89,6 +107,7 @@ mk_langs!(
     ),
     (
         Python,
+        "The `Python` language",
         "python",
         PythonCode,
         PythonParser,
@@ -98,6 +117,7 @@ mk_langs!(
     ),
     (
         Tsx,
+        "The `Tsx` language incorporates the `JSX` syntax inside `TypeScript`",
         "typescript",
         TsxCode,
         TsxParser,
@@ -107,6 +127,7 @@ mk_langs!(
     ),
     (
         Typescript,
+        "The `TypeScript` language",
         "typescript",
         TypescriptCode,
         TypescriptParser,
@@ -116,6 +137,7 @@ mk_langs!(
     ),
     (
         Ccomment,
+        "The `Ccomment` language is a variant of the `C` language focused on comments",
         "ccomment",
         CcommentCode,
         CcommentParser,
@@ -125,6 +147,7 @@ mk_langs!(
     ),
     (
         Preproc,
+        "The `PreProc` language is a variant of the `C/C++` language focused on macros",
         "preproc",
         PreprocCode,
         PreprocParser,