Comment for client function (#469)

This change adds comments for the functions that each client has for
YARD and IDE purposes.

Since YARD seems to report errors if the comments are incorrect, This
change also ensures that the command is executed in the CI job.

Author: Yang-33

.github/workflows/pull_request.yml

@@ -35,6 +35,7 @@ jobs:
     - run: bundle install
     - run: bundle exec rubocop
     - run: bundle exec rspec
+    - run: bundle exec yard stats ./lib/line/bot/v2 --fail-on-warning
 
   rbs:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -1,15 +1,45 @@
-## How to contribute to LINE Bot SDK for Ruby project
+# How to contribute to LINE Bot SDK for Ruby project
 
-First of all, thank you so much for taking your time to contribute! LINE Bot SDK for Ruby is not very different from any other open
-source projects you are aware of. It will be amazing if you could help us by doing any of the following:
+First of all, thank you so much for taking your time to contribute!
+LINE Bot SDK for Ruby is not very different from any other open source projects you are aware of.
+It will be amazing if you could help us by doing any of the following:
 
-- File an issue in [the issue tracker](https://github.com/line/line-bot-sdk-ruby/issues) to report bugs and propose new features and
-  improvements.
+- File an issue in [the issue tracker](https://github.com/line/line-bot-sdk-ruby/issues) to report bugs and propose new features and improvements.
 - Ask a question using [the issue tracker](https://github.com/line/line-bot-sdk-ruby/issues).
 - Contribute your work by sending [a pull request](https://github.com/line/line-bot-sdk-ruby/pulls).
 
+## Development
+
+### YARD
+
+We use [YARD](https://yardoc.org) to generate and maintain our code documentation.
+**Please make sure your new or modified code is also covered by proper YARD doc comments.**
+Good documentation ensures that contributors and users can easily read and understand how the methods and classes work.
+
+#### How to generate and view documentation locally
+
+##### 1. **Start a local documentation server**
+
+Run the following command to start a local YARD server that will automatically reload when files change:
+
+```bash
+bundle exec yard server --reload
+```
+
+Then open the printed URL in your browser (e.g., http://localhost:8808).
+
+##### 2. **Validate your documentation**  
+
+Before pushing your changes, run the following command to check YARD documentation coverage and warnings:
+```bash
+bundle exec yard stats ./lib/line/bot/v2 --fail-on-warning
+```
+This will fail if there are missing doc comments or any YARD-specific warnings.
+Make sure to fix any issues before creating a pull request.
+
+For more details on how to write YARD doc comments, refer to YARD’s official [Getting Started guide](https://rubydoc.info/gems/yard/file/docs/GettingStarted.md).
+
 ### Contributor license agreement
 
-When you are sending a pull request and it's a non-trivial change beyond fixing typos, please make sure to sign
-[the ICLA (individual contributor license agreement)](https://cla-assistant.io/line/line-bot-sdk-ruby). Please
-[contact us](mailto:dl_oss_dev@linecorp.com) if you need the CCLA (corporate contributor license agreement).
+When you are sending a pull request and it's a non-trivial change beyond fixing typos, please make sure to sign [the ICLA (individual contributor license agreement)](https://cla-assistant.io/line/line-bot-sdk-ruby).
+Please [contact us](mailto:dl_oss_dev@linecorp.com) if you need the CCLA (corporate contributor license agreement).

Gemfile

@@ -6,7 +6,9 @@ gem 'multipart-post', '~> 2.4.1', require: false
 
 group :development, :test do
   # ref: http://docs.rubocop.org/en/latest/installation/
+  gem 'rack', '~> 2.2'
   gem 'rubocop', '~> 1.75.0', require: false
+  gem 'webrick', '~> 1.9.1'
   gem 'yard', '~> 0.9.20'
 end
 

Gemfile.lock

@@ -27,6 +27,7 @@ GEM
     prism (1.4.0)
     public_suffix (6.0.1)
     racc (1.8.1)
+    rack (2.2.13)
     rainbow (3.1.1)
     rake (13.2.1)
     regexp_parser (2.10.0)
@@ -66,20 +67,24 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    webrick (1.9.1)
     yard (0.9.37)
 
 PLATFORMS
+  arm64-darwin-21
   arm64-darwin-22
   x86_64-linux
 
 DEPENDENCIES
   addressable (~> 2.3)
   line-bot-api!
   multipart-post (~> 2.4.1)
+  rack (~> 2.2)
   rake (~> 13.0)
   rspec (~> 3.13.0)
   rubocop (~> 1.75.0)
   webmock (~> 3.25.0)
+  webrick (~> 1.9.1)
   yard (~> 0.9.20)
 
 BUNDLED WITH

generator/src/main/resources/line-bot-sdk-ruby-generator/api.pebble

@@ -55,12 +55,10 @@ module Line
           {%- for op in operations.operation %}
 
           # {{ op.notes }}
+          # This requests to <code>{{ op.httpMethod }} {{ endpoint(operations.classname) }}{{ op.path }}</code>
           #
-          {%  if op.summary -%}
-          # @summary {{ op.summary }}
-          {%  endif -%}
           {% for param in op.allParams -%}
-          # @param {{param.paramName}} {{param.description}}
+          # @param {{param.paramName}} [{{ param.dataType }}{{ param.required ? '' : ', nil' }}] {{param.description}}
           {% endfor -%}
           {% if op.isDeprecated -%}
           # @deprecated
@@ -70,7 +68,15 @@ module Line
           {% endif -%}
           {% if op.externalDocs.url != null -%}
           # @see {{op.externalDocs.url}}
-          {% endif -%}
+          {%- endif %}
+          # @return [response body, response status code, and response headers]
+          {%- for response in op.responses %}
+          {%- if response.content['application/json'].schema.complexType != null %}
+          # @return [Array(Line::Bot::V2::{{ packageName | camelize }}::{{ response.content['application/json'].schema.complexType }}, Integer, Hash{String => String})] when HTTP status code is {{ response.code }}
+          {%- else %}
+          # @return [Array(String(nilable), Integer, Hash{String => String})] when HTTP status code is {{ response.code }}
+          {%- endif %}
+          {%- endfor %}
           def {{op.nickname}}_with_http_info({% for param in op.allParams %}
             {{param.paramName}}:{{ param.required ? '' : ' nil' }}{{ loop.last ? '' : ',' -}}
             {% endfor %}
@@ -120,12 +126,11 @@ module Line
           end
 
           # {{ op.notes }}
+          # This requests to <code>{{ op.httpMethod }} {{ endpoint(operations.classname) }}{{ op.path }}</code>
+          # When you want to get HTTP status code or response headers, use {{ '{#' }}{{op.nickname}}_with_http_info} instead of this.
           #
-          {%  if op.summary -%}
-          # @summary {{ op.summary }}
-          {%  endif -%}
           {% for param in op.allParams -%}
-          # @param {{param.paramName}} {{param.description}}
+          # @param {{param.paramName}} [{{ param.dataType }}{{ param.required ? '' : ', nil' }}] {{param.description}}
           {% endfor -%}
           {% if op.isDeprecated -%}
           # @deprecated
@@ -135,7 +140,14 @@ module Line
           {% endif -%}
           {% if op.externalDocs.url != null -%}
           # @see {{op.externalDocs.url}}
-          {% endif -%}
+          {%- endif %}
+          {%- for response in op.responses %}
+          {%- if response.content['application/json'].schema.complexType != null %}
+          # @return [Line::Bot::V2::{{ packageName | camelize }}::{{ response.content['application/json'].schema.complexType }}] when HTTP status code is {{ response.code }}
+          {%- else %}
+          # @return [String, nil] when HTTP status code is {{ response.code }}
+          {%- endif %}
+          {%- endfor %}
           def {{op.nickname}}({% for param in op.allParams %}
             {{param.paramName}}:{{ param.required ? '' : ' nil' }}{{ loop.last ? '' : ',' -}}
             {% endfor %}

generator/src/main/resources/line-bot-sdk-ruby-rbs-generator/api.pebble

@@ -19,9 +19,6 @@ module Line
 
           # {{ op.notes }}
           #
-          {%  if op.summary -%}
-          # @summary {{ op.summary }}
-          {%  endif -%}
           {% for param in op.allParams -%}
           # @param {{ param.paramName }} {{ param.description }}
           {% endfor -%}
@@ -42,9 +39,6 @@ module Line
 
           # {{ op.notes }}
           #
-          {%  if op.summary -%}
-          # @summary {{ op.summary }}
-          {%  endif -%}
           {% for param in op.allParams -%}
            # @param {{ param.paramName }} {{ param.description }}
           {% endfor -%}