From 749c53527ef6ce4e6262b5fed4fb570bb7d89940 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?fn=20=E2=8C=83=20=E2=8C=A5?= <70830482+FnControlOption@users.noreply.github.com> Date: Tue, 26 Oct 2021 21:03:30 -0700 Subject: [PATCH] Add documentation --- src/ameba/config.cr | 1 + src/ameba/runner.cr | 1 + src/ameba/source.cr | 2 ++ src/ameba/source/corrector.cr | 15 +++++++++++++++ src/ameba/source/rewriter.cr | 2 +- src/ameba/source/rewriter/action.cr | 1 + 6 files changed, 21 insertions(+), 1 deletion(-) diff --git a/src/ameba/config.cr b/src/ameba/config.cr index ba9f6889..91fad3cc 100644 --- a/src/ameba/config.cr +++ b/src/ameba/config.cr @@ -54,6 +54,7 @@ class Ameba::Config # ``` property excluded : Array(String) + # Returns true if correctable issues should be autocorrected. property? autocorrect = false @rule_groups : Hash(String, Array(Rule::Base)) diff --git a/src/ameba/runner.cr b/src/ameba/runner.cr index c22ad752..3cccff4d 100644 --- a/src/ameba/runner.cr +++ b/src/ameba/runner.cr @@ -50,6 +50,7 @@ module Ameba # Checks for unneeded disable directives. Always inspects a source last @unneeded_disable_directive_rule : Rule::Base? + # Returns true if correctable issues should be autocorrected. private getter? autocorrect : Bool # Instantiates a runner using a `config`. diff --git a/src/ameba/source.cr b/src/ameba/source.cr index ccd71af1..8e27c242 100644 --- a/src/ameba/source.cr +++ b/src/ameba/source.cr @@ -25,6 +25,8 @@ module Ameba def initialize(@code, @path = "") end + # Corrects any correctable issues and updates `code`. + # Returns `false` if no issues were corrected. def correct corrector = Corrector.new(code) issues.each(&.correct(corrector)) diff --git a/src/ameba/source/corrector.cr b/src/ameba/source/corrector.cr index f4adf1da..ab6823ef 100644 --- a/src/ameba/source/corrector.cr +++ b/src/ameba/source/corrector.cr @@ -1,6 +1,8 @@ require "./rewriter" class Ameba::Source + # This class takes source code and rewrites it based + # on the different correction actions supplied. class Corrector @line_sizes : Array(Int32) @@ -9,30 +11,37 @@ class Ameba::Source @line_sizes = code.lines(chomp: false).map(&.size) end + # Replaces the code of the given range with *content*. def replace(location, end_location, content) @rewriter.replace(loc_to_pos(location), loc_to_pos(end_location) + 1, content) end + # Inserts the given strings before and after the given range. def wrap(location, end_location, insert_before, insert_after) @rewriter.wrap(loc_to_pos(location), loc_to_pos(end_location) + 1, insert_before, insert_after) end + # Shortcut for `replace(location, end_location, "")` def remove(location, end_location) @rewriter.remove(loc_to_pos(location), loc_to_pos(end_location) + 1) end + # Shortcut for `wrap(location, end_location, content, nil)` def insert_before(location, end_location, content) @rewriter.insert_before(loc_to_pos(location), loc_to_pos(end_location) + 1, content) end + # Shortcut for `wrap(location, end_location, nil, content)` def insert_after(location, end_location, content) @rewriter.insert_after(loc_to_pos(location), loc_to_pos(end_location) + 1, content) end + # Shortcut for `insert_before(location, location, content)` def insert_before(location, content) @rewriter.insert_before(loc_to_pos(location), content) end + # Shortcut for `insert_after(location, location, content)` def insert_after(location, content) @rewriter.insert_after(loc_to_pos(location) + 1, content) end @@ -46,22 +55,27 @@ class Ameba::Source @line_sizes[0...line - 1].sum + (column - 1) end + # Replaces the code of the given node with *content*. def replace(node : Crystal::ASTNode, content) replace(location(node), end_location(node), content) end + # Inserts the given strings before and after the given node. def wrap(node : Crystal::ASTNode, insert_before, insert_after) wrap(location(node), end_location(node), insert_before, insert_after) end + # Shortcut for `replace(node, "")` def remove(node : Crystal::ASTNode) remove(location(node), end_location(node)) end + # Shortcut for `wrap(node, content, nil)` def insert_before(node : Crystal::ASTNode, content) insert_before(location(node), content) end + # Shortcut for `wrap(node, nil, content)` def insert_after(node : Crystal::ASTNode, content) insert_after(end_location(node), content) end @@ -74,6 +88,7 @@ class Ameba::Source node.end_location || raise "Missing end location" end + # Applies all scheduled changes and returns modified source as a new string. def process @rewriter.process end diff --git a/src/ameba/source/rewriter.cr b/src/ameba/source/rewriter.cr index 62b5c65b..6825ea87 100644 --- a/src/ameba/source/rewriter.cr +++ b/src/ameba/source/rewriter.cr @@ -70,7 +70,7 @@ class Ameba::Source @action_root.empty? end - # Replaces the code of the given range with `content`. + # Replaces the code of the given range with *content*. def replace(begin_pos, end_pos, content) combine(begin_pos, end_pos, replacement: content.to_s) end diff --git a/src/ameba/source/rewriter/action.cr b/src/ameba/source/rewriter/action.cr index c33e607c..df4d1270 100644 --- a/src/ameba/source/rewriter/action.cr +++ b/src/ameba/source/rewriter/action.cr @@ -1,4 +1,5 @@ class Ameba::Source::Rewriter + # :nodoc: # Actions are arranged in a tree and get combined so that: # - children are strictly contained by their parent # - siblings all disjoint from one another and ordered