From f175c4209706606327510ebf89af71f7220e6586 Mon Sep 17 00:00:00 2001
From: Kanezoh <asfaltmanta114@gmail.com>
Date: Thu, 14 Oct 2021 20:42:33 +0900
Subject: [PATCH] add comment

---
 src/mechanize.cr                       | 30 +++++++++++++++++---------
 src/mechanize/page.cr                  | 18 ++++++++++------
 src/mechanize/utils/element_matcher.cr | 15 ++++++++++++-
 3 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/src/mechanize.cr b/src/mechanize.cr
index 6660bf7..9c87ceb 100644
--- a/src/mechanize.cr
+++ b/src/mechanize.cr
@@ -159,6 +159,7 @@ class Mechanize
     end
   end
 
+  # parse response. it is used internally.
   def parse(uri, response, body)
     code = response.not_nil!.status_code
     MechanizeCr::Page.new(uri, response, body, code, self)
@@ -169,7 +170,7 @@ class Mechanize
   # ```
   # agent.history => #<MechanizeCr::History>
   # ```
-  def history
+  def history : MechanizeCr::History
     @agent.history
   end
 
@@ -186,29 +187,38 @@ class Mechanize
   # ```
   # agent.max_history # => 100
   # ```
-  def max_history
+  def max_history : Int32
     history.max_size
   end
 
-  # Set maximum number of pages allowed in the history.
-  # The default setting is 100 pages.
+  # set maximum number of pages allowed in the history.
+  # the default value is 100.
   # ```
   # agent.max_history = 150
   # ```
-  def max_history=(length)
+  def max_history=(length : Int32)
     history.max_size = length
   end
 
-  # click link, and return page.
-  def click(link)
+  # click link, and transit page.
+  #
+  # ```
+  # page = agent.get("http://example.com")
+  # link = page.links.first
+  # page2 = agent.click(link)
+  # ```
+  def click(link : MechanizeCr::PageContent::Link) : MechanizeCr::Page
     href = link.href
     get href
   end
 
   # download page body from given uri.
-  # TODO: except this request from history.
-  def download(uri,
-               filename,
+  # ```
+  # # make download.html whose content is http://example.com's html.
+  # agent.download("http://example.com", "download.html")
+  # ```
+  def download(uri : URI | String,
+               filename : String,
                headers = HTTP::Headers.new,
                params : Hash(String, String | Array(String)) = Hash(String, String).new)
     transact do
diff --git a/src/mechanize/page.cr b/src/mechanize/page.cr
index c725007..9b082bd 100644
--- a/src/mechanize/page.cr
+++ b/src/mechanize/page.cr
@@ -2,6 +2,10 @@ require "./file"
 require "./utils/element_matcher"
 require "./page/link"
 
+# This class represents the page of response.
+# If you send request, it returns the instance of Page.
+# You can get status code, title, and page body, and search html node using css selector.
+
 class MechanizeCr::Page < MechanizeCr::File
   include MechanizeCr::ElementMatcher
   delegate :css, to: parser
@@ -13,11 +17,14 @@ class MechanizeCr::Page < MechanizeCr::File
     super(uri, response, body, code)
   end
 
+  # parser to parse response body.
+  # TODO: now it's Lexbor::Parser. I want to also support other parsers like JSON.
   def parser : Lexbor::Parser
     @parser ||= Lexbor::Parser.new(@body)
   end
 
-  def title
+  # return page title.
+  def title : String
     title_node = css("title")
     if title_node.empty?
       ""
@@ -26,7 +33,8 @@ class MechanizeCr::Page < MechanizeCr::File
     end
   end
 
-  def forms
+  # return all forms(`MechanizeCr::Form`) in the page.
+  def forms : Array(MechanizeCr::Form)
     forms = css("form").map do |html_form|
       form = Form.new(html_form, self)
       form.action ||= @uri.to_s
@@ -34,7 +42,8 @@ class MechanizeCr::Page < MechanizeCr::File
     end.to_a
   end
 
-  def links
+  # return all links(`MechanizeCr::PageContent::Link) in the page.
+  def links : Array(MechanizeCr::PageContent::Link)
     links = %w{a area}.map do |tag|
       css(tag).map do |node|
         PageContent::Link.new(node, @mech, self)
@@ -42,8 +51,5 @@ class MechanizeCr::Page < MechanizeCr::File
     end.flatten
   end
 
-  # generate form_with, forms_with methods
-  # ex) form_with({:name => "login_form"})
-  # it detects form(s) which match conditions.
   elements_with "form"
 end
diff --git a/src/mechanize/utils/element_matcher.cr b/src/mechanize/utils/element_matcher.cr
index 9194016..70c2056 100644
--- a/src/mechanize/utils/element_matcher.cr
+++ b/src/mechanize/utils/element_matcher.cr
@@ -1,7 +1,20 @@
 module MechanizeCr::ElementMatcher
   macro elements_with(singular, plural = "")
     {% plural = "#{singular.id}s" if plural.empty? %}
-    def {{plural.id}}_with(criteria)
+    # search {{ singular.id }} which matches condition.
+    # 
+    # Examples
+    # ```
+    # # if you specify String like "foo", it searches form which name is "foo".
+    # # like {<form name="foo"></form>}
+    # page.form_with("foo") 
+    # 
+    # # you can specify tag's attribute and its' value by NamedTuple or Hash(String, String).
+    # ex) <form class="foo"></form>
+    # page.form_with("class" => "foo")
+    # page.form_with(class: "foo")
+    # ```
+    def {{plural.id}}_with(criteria : String | NamedTuple | Hash(String,String))
       {{plural.id}}_with(criteria){}
     end