Add doc comments to functions

src/ast_parsing.rs

@@ -1,12 +1,17 @@
 use crate::parsing::extract_docstring;
 use tree_sitter::{Node, Point};
 
+/// Information about a function's signature and docstring.
 pub(crate) struct FunctionInfo<'a, 'b> {
     pub(crate) params: &'b [(&'a str, Option<&'a str>)],
     pub(crate) docstring: Option<&'a str>,
     pub(crate) start_position: Point,
 }
 
+/// Extracts function information from a node if it is a function definition.
+///
+/// Uses a buffered params vector for performance, instead of allocating a new one
+/// every time.
 pub(crate) fn get_function_signature<'a, 'b>(
     node: &Node,
     source_code: &'a str,

src/main.rs

@@ -43,6 +43,7 @@ struct Args {
     docstyle: DocstringStyle,
 }
 
+/// Determines if a file or folder is hidden, i.e. if it starts with '.'.
 fn is_hidden(e: &DirEntry) -> bool {
     e.file_name()
         .to_str()
@@ -141,7 +142,8 @@ fn main() -> Result<()> {
     }
 }
 
-fn assess_success(entry: &Path, args: &Args, global_success: &AtomicU32) {
+/// Determines if the file has errors or not, increasing error count if it does.
+fn assess_success(entry: &Path, args: &Args, total_errors: &AtomicU32) {
     if entry.is_file() && entry.extension() == Some(&std::ffi::OsString::from("py")) {
         let Ok(success) = is_file_compliant(
             entry,
@@ -155,11 +157,12 @@ fn assess_success(entry: &Path, args: &Args, global_success: &AtomicU32) {
         };
 
         if !success {
-            global_success.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+            total_errors.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
         }
     }
 }
 
+/// Determines if a file is compliant to the specified rules.
 fn is_file_compliant(
     path: &Path,
     break_on_empty_line: bool,

src/parsing.rs

@@ -165,6 +165,7 @@ pub fn parse_numpy_docstring(
     Some(params)
 }
 
+/// Extracts the docstring from a block of a function's contents.
 pub fn extract_docstring(content: &str) -> Option<&str> {
     if let Some(stripped_content) = content.strip_prefix(r#"""""#) {
         let ending = stripped_content.find(r#"""""#)? + 6;

src/rules_checking.rs

@@ -15,6 +15,7 @@ pub enum DocstringStyle {
     AutoDetect,
 }
 
+/// Walks recursively through a tree applying a closure on each node.
 fn walk_rec<F>(cursor: &mut TreeCursor, closure: &mut F)
 where
     for<'a> F: FnMut(&Node),
@@ -34,6 +35,7 @@ where
     cursor.goto_parent();
 }
 
+/// Checks if the source code respects the specified rules.
 #[allow(clippy::too_many_arguments)]
 pub fn respects_rules(
     parser: &mut Parser,
@@ -75,6 +77,7 @@ pub fn respects_rules(
     success
 }
 
+/// Checks if a given function respects the specified rules.
 fn is_function_info_valid(
     info: &FunctionInfo,
     path: Option<&Path>,