sf_cli 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98f07645a79ccfa6a8f8bbac048a4da5aae6f21bf294445a0888f861d91b8f27
-  data.tar.gz: a608a4eeb21ff2fd065cac874d6834e1a6c8aec83f9a40ada0f73917e4029ffb
+  metadata.gz: fa13644d7e9281efbbb57516775a5edd9b69fb7ff9fbc260332a54d0afebc227
+  data.tar.gz: feb9c574b8d0681fbe9ba43572cb9b7725558fc20f69eebbbd3a2b3734aa60b9
 SHA512:
-  metadata.gz: 9f5949bdba034feb1a7265a79fa9cd41c9e6f9d1402e4cf173fc585b0ab44d904570591382066633f5258f55503f0503410d648fb3700856029471678090efed
-  data.tar.gz: 32a39625a575b1f9e465d9090c1e63a0ec8ee8ed605c4f5c3104b3866121a931780cf7c2f82200ab84ca5924ff798790cf116cf9580280ab1e1e6a26458d1ef4
+  metadata.gz: ade35b3acd147ac13367c6d681c31028fef4b661ab2a97101e21b170221231c81c8d76a13c9e6f2688b085ae4889c8872ced4dd72b4f1d21cc8ac465cde78096
+  data.tar.gz: f7fb45fc3c50d2ab557f82d28b74119465fddad2c5930710aadbe0b44c19da49b8ac76c6815f0e18132d0f49d1590ed456ed42069ca07385e75db3d630f0812e

data/{rdoc/README.rdoc → README.rdoc}

@@ -5,75 +5,61 @@ This is a class library for introducing {Salesforce CLI}[https://developer.sales
 It is designed to be similar usability to the original command.<br>
 Currently only *sf* command is the target of development.
 
+[rubygems]          https://rubygems.org/gems/sf_cli
+[official document] https://tmkw.github.io/sf_cli/
+
 == prerequisite
-Salesforce CLI must be installed.<br>
+{Salesforce CLI}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm] must be installed.<br>
 As of as of September in 2024, ver.2.56.7 is the development target.
 
 == install
 Rubygem::
-    the simplest way:
-        $ gem install sf_cli
+  the simplest way:
+    $ gem install sf_cli
 Bundler::
-    in Gemfile:
-        gem 'sf_cli'
-    then,
-        $ bundle install
-== Documents
-Class Library Reference::
-    {Online document}[https://www.rubydoc.info/gems/sf_cli/0.0.7] at rubygems.org
-
-    Or,
-    Generate locally:
-      $ git clone https://github.com/tmkw/sf_cli.git
-      $ cd sf_cli
-      $ bundle install
-      $ bundle exec rake rdoc
-    *As* *of* *0.0.7*, *this* *may* *be* *better* *to* *know* *what* *it* *is* *exactly*.
-Salesforce CLI and Sf command::
-    1. {Salesforce CLI reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm]
-    2. {sf command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_unified.htm]
-
-== Short Examples
+  in Gemfile:
+    gem 'sf_cli'
+  then,
+    $ bundle install
+== Usage
+Load module
   require 'sf_cli'
 
-  # login to org
+Login to org
   sf.org.login_web
 
-  # get salesforce object schema 
+Get Salesforce Object schema 
   sf.sobject.describe :Account
 
-  # get a record
+Get a record
   sf.data.get_record :Account, record_id: 'xxxxxxx'
   sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}
 
-  # execute soql
+Execute SOQL
   sf.data.query "SELECT Id, Name FROM Account LIMIT 1" # => [{Id: "abc", Name: "account name"}]
 
-  # create a record
+Create a record
   sf.data.create_record :TheCustomObject__c, values: {Name: "John Smith", Age: 33}
 
-  # update a record
+Update a record
   sf.data.update_record :Account, record_id: 'xxxxxxx', values: {Name: 'New Account Name'}
   sf.data.update_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}, values: {Phone: 'xxxxx', bar: 2000}
 
-  # delete a record
+Delete a record
   sf.data.delete_record :Hoge__c, record_id: 'xxxxxxx'
   sf.data.delete_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}
 
-  # using Bulk API 2.0
+Using Bulk API 2.0
   sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.csv', timeout: 5  # waiting for 5 minutes at maximum
 
-  # run Apex
+Run Apex
   sf.apex.run file: 'path/to/file'
   sf.apex.run file: StringIO.new("System.debug('Hello World')")
-== \Object Model Support
-As of now, there is experimental support for object model in Salesforce.
-=== Short examples
-===== With sf command:
+== Object Model Support (experimental)
+With sf command:
   rows = sf.data.query "SELECT Id, Name FROM Contact WHERE Name = 'Akin Kristen'", model_class: Contact
   rows.first      # <Contact: @Id="0035j00001RW3xbAAD", @Name="Akin Kristen">
   rows.first.Name # Akin Kristen
-===== Doing the same thing with model independently
+Doing the same thing independently:
   contact = Contact.select(:Id, :Name).where(Name: 'Akin Kristen').take
   contact.Name # Akin Kristen
-For more details, take a look at {the object model section}[link://files/rdoc/ObjectModel_rdoc.html]

data/lib/sf_cli/console/commands.rb

@@ -0,0 +1,36 @@
+require 'sf_cli'
+require 'sf_cli/sf/model'
+require 'sf_cli/sf/model/sf_command_connection'
+require 'stringio'
+
+module SfCli
+  module Console
+    module Commands
+      def use(_target_org)
+        target_org = _target_org.to_sym == :default ? nil : _target_org
+        org_info = sf.org.display target_org: target_org
+        conn = SfCli::Sf::Model::SfCommandConnection.new target_org: target_org, instance_url: org_info.instance_url
+        SfCli::Sf::Model.set_connection conn
+      end
+
+      def generate(*object_types)
+        SfCli::Sf::Model.generate object_types
+      end
+
+      def connection
+        SfCli::Sf::Model.connection
+      end
+
+      def target_org
+        connection.target_org
+      end
+
+      def apex(apex_code)
+        sf.apex.run target_org: target_org, file: StringIO.new(apex_code)
+      end
+
+      alias :gen  :generate
+      alias :conn :connection
+    end
+  end
+end

data/lib/sf_cli/console.rb

@@ -0,0 +1,5 @@
+require 'sf_cli/console/commands'
+
+include SfCli::Console::Commands
+
+use ARGV[0]

data/lib/sf_cli/sf/apex/core.rb

@@ -3,13 +3,12 @@ require_relative './run'
 
 module SfCli
   module Sf
+    # Apex Commands
+    #
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_apex_commands_unified.htm command reference
+    #
     module Apex
-      #
-      # ==== description
-      # The class representing *sf* *apex*.
-      #
-      # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_apex_commands_unified.htm
-      #
+      # @private :nodoc: just for developers
       class Core
         include ::SfCli::Sf::Core::Base
         include Run

data/lib/sf_cli/sf/apex/run.rb

@@ -4,19 +4,25 @@ require 'stringio'
 module SfCli::Sf::Apex
   module Run
     #
-    # run apex code and returns its result
+    # Run apex code and returns its result.
+    # If you don't specify the script file, it starts interactive mode.
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_apex_commands_unified.htm#cli_reference_apex_run_unified CLI reference
     #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
+    # @param target_org [Symbol,String]
+    #   an alias of paticular org, or username can be used.
     #
-    # *file* --- (1) path to a local file that contains \Apex code. (2) StringIO object
+    # @param file [String,StringIO]
+    #   (1) path to a local file that contains Apex code. 
+    #   (2) StringIO object
     #
-    # == Examples
-    # Execute apex code in a file
+    # @return [ApexResult] Apex execution result.
+    #
+    # @example Execute apex code in a file
     #   result = sf.apex.run file: "path/to/apex"
     #   result.success # true if the execution succeeds
     #   result.logs    # execution log
     #
-    # StringIO is usable instead of file path
+    # @example StringIO is usable instead of file path
     #   require 'stringio'
     #
     #   pseudo_file = StringIO.new <<~EOS
@@ -26,9 +32,7 @@ module SfCli::Sf::Apex
     #
     #   sf.apex.run target_org: :dev, file: pseudo_file
     #
-    # == Interactive Mode
-    #
-    # If you don't specify *file* argument, it starts interactive mode that may be helpful in IRB environment.
+    # @example Interactive Mode
     #   irb(main:) > sf.apex.run target_org: :dev
     #
     #   Account acc = [SELECT Id, Name FROM Account LIMIT 1];
@@ -48,7 +52,6 @@ module SfCli::Sf::Apex
     #       "Execute Anonymous: Account acc = [SELECT Id, Name FROM Account LIMIT 1];",
     #       "Execute Anonymous: System.debug(acc.Name);",
     #      ....]
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_apex_commands_unified.htm#cli_reference_apex_run_unified]
     #
     def run(target_org: nil, file: nil)
       return run_interactive(target_org) if file.nil?

data/lib/sf_cli/sf/core/base.rb

@@ -2,6 +2,7 @@ require 'json'
 
 module SfCli
   module Sf
+    # @private :nodoc: just for developers
     module Core
       module Base
         attr_reader :varbose

data/lib/sf_cli/sf/data/bulk_result_v2.rb

@@ -1,7 +1,6 @@
 module SfCli
   module Sf
     module Data
-      #
       # Bulk Job information.
       #
       # You can check the job status using the following method:
@@ -9,11 +8,11 @@ module SfCli
       # - upload_completed?
       # - in_progress?
       # - completed?
-      # ==== example:
+      # @example
       #   result = sf.data.delete_resume job_id: jobinfo.id
       #   puts 'yey!' if result.job_info.completed? # the job has completed
       #
-      # For more details, see {the guide document}[https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_job_states.htm]
+      # See Also: {https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_job_states.htm the guide document}
       #
       JobInfo = Struct.new(
         :id,

data/lib/sf_cli/sf/data/core.rb

@@ -13,13 +13,12 @@ require_relative './search'
 
 module SfCli
   module Sf
+    #
+    # Data Command
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm command reference
+    #
     module Data
-      #
-      # ==== description
-      # The class representing *sf* *data*
-      #
-      # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm
-      #
+      # @private :nodoc: just for developers
       class Core
         include ::SfCli::Sf::Core::Base
         include Query

data/lib/sf_cli/sf/data/create_record.rb

@@ -1,19 +1,17 @@
 module SfCli::Sf::Data
   module CreateRecord
     # create a object record.
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_create_record_unified command reference
+    # @param object_type [Symbol, String] object type(ex. Account)
+    # @param values      [Hash]           field values to be assigned
+    # @param target_org  [Symbol, String] an alias of paticular org, or username can be used
     #
-    # *object_type* --- \Object Type (ex. Account)<br>
+    # @return [String] record ID
     #
-    # *values* --- field values to be assigned<br>
-    #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
-    #
-    # ======
+    # @example
     #   # create a TheCustomObject record with name and age
     #   sf.data.create_record :TheCustomObject__c, values: {Name: "John Smith", Age: 33}
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_create_record_unified]
-    #
     def create_record(object_type, values: {}, target_org: nil)
       field_values = field_value_pairs(values)
       flags = {

data/lib/sf_cli/sf/data/delete_bulk.rb

@@ -2,17 +2,15 @@ require_relative './bulk_result_v2'
 
 module SfCli::Sf::Data
   module DeleteBulk
-    # delete records using Bulk API 2.0
+    # Delete records using Bulk API 2.0
+    # @param file       [String]         path of a CSV file, which is written record IDs to delete
+    # @param sobject    [Symbol, String] object type (ex. Account)
+    # @param timeout    [Integer]        max minutes to wait for the job complete the task.
+    # @param target_org [Symbol, String] an alias of paticular org, or username can be used
     #
-    # *file* --- a CSV file, which is written record IDs to delete<br>
+    # @return [JobInfo, BulkResultV2] the job result, whose type is changed by situation
     #
-    # *sobject* --- \Object Type (ex. Account)<br>
-    #
-    # *timeout* --- max minutes to wait for the job complete the task.<br>
-    #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
-    #
-    # ======
+    # @example
     #   # start a delete job
     #   jobinfo = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv' # this returns immediately
     #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
@@ -23,7 +21,8 @@ module SfCli::Sf::Data
     #   # Or, you can wait for the job completion with one try.
     #   result = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv', timeout: 5  # wait within 5 minutes
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_bulk_unified]
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_bulk_unified command reference
+    #
     #
     def delete_bulk(file:, sobject:, timeout: nil, target_org: nil)
       flags = {

data/lib/sf_cli/sf/data/delete_record.rb

@@ -1,20 +1,19 @@
 module SfCli::Sf::Data
   module DeleteRecord
-    # delete a object record.
+    # Delete a object record.
     #
-    # *object_type* --- \Object Type (ex. Account)<br>
+    # @param object_type [Symbol, String] Object Type (ex. Account)
+    # @param record_id   [String]         Id of the object
+    # @param where       [Hash]           conditions to identify a record
+    # @param target_org  [Symbol, String] an alias of paticular org, or username can be used
     #
-    # *record_id* --- id of the object<br>
+    # @return [String] ID that is deleted.
     #
-    # *where* --- hash object that is used to identify a record<br>
-    #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
-    #
-    # ======
+    # @example
     #   sf.data.delete_record :Hoge__c, record_id: 'xxxxxxx'
     #   sf.data.delete_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_record_unified]
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_record_unified the command reference
     #
     def delete_record(object_type, record_id: nil, where: nil, target_org: nil)
       where_conditions = field_value_pairs(where)

data/lib/sf_cli/sf/data/delete_resume.rb

@@ -2,15 +2,15 @@ require_relative './bulk_result_v2'
 
 module SfCli::Sf::Data
   module DeleteResume
-    # resume a bulk delete job you previously started with Bulk API 2.0 and return a bulk result object.
+    # Resume a bulk delete job you previously started with Bulk API 2.0 and return a bulk result object.
     #
-    # *job_id* ---  job ID you want to resume<br>
+    # @param job_id     [String]         job ID you want to resume<br>
+    # @param timeout    [Integer]        max minutes to wait for the job complete the task.<br>
+    # @param target_org [Symbol, String] an alias of paticular org, or username can be used<br>
     #
-    # *timeout* --- max minutes to wait for the job complete the task.<br>
+    # @return [JobInfo, BulkResultV2] the job result, whose type is changed by situation
     #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
-    #
-    # ======
+    # @example
     #   # start a delete job
     #   jobinfo = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv' # this returns immediately
     #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
@@ -22,9 +22,7 @@ module SfCli::Sf::Data
     #
     #   puts 'yey!' if result.job_info.completed? # the job has completed
     #
-    # To know more about a job result, take a look at SfCli::Sf::Data module
-    #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_resume_unified]
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_resume_unified the command reference
     #
     def delete_resume(job_id:, timeout: nil, target_org: nil)
       flags = {

data/lib/sf_cli/sf/data/get_record.rb

@@ -1,26 +1,24 @@
 module SfCli::Sf::Data
   module GetRecord
 
-    # get a object record. (eqivalent to *sf* *data* *get* *record*)
+    # Get a object record.
+    # @param object_type [Symbol,String] object type(ex. Account)
+    # @param record_id   [String]        id of the object
+    # @param where       [Hash]          conditions to identify a record
+    # @param target_org  [Symbol,String] an alias of paticular org, not default one
+    # @param model_class [Class]         the object model class
     #
-    # *object_type* --- \Object Type (ex. Account)<br>
+    # @return [Hash,Class] if proper model class is specified, the return value is the instance of the class. Otherwise, it's a Hash object.
     #
-    # *record_id* --- id of the object<br>
-    #
-    # *where* --- hash object that is used to identify a record<br>
-    #
-    # *target_org* --- an alias of paticular org, not default one<br>
-    #
-    # *model_class* --- the object model class<br>
-    #
-    # ======
+    # @example
     #   sf.data.get_record :Account, record_id: 'xxxxxxx'
     #   sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}
     #
     #   CustomObject = Struct.new(:Id, :Name)
-    #   sf.data.get_record :TheCustomObject__c, record_id: 'xxxxx', model_class: CustomObject  # returns a CustomObject instance
+    #   obj = sf.data.get_record :TheCustomObject__c, record_id: 'xxxxx', model_class: CustomObject # returns a CustomObject instance
+    #   obj.Name # Name field of the record
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_get_record_unified]
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_get_record_unified command reference
     #
     def get_record(object_type, record_id: nil, where: nil, target_org: nil, model_class: nil)
       where_conditions = field_value_pairs(where)

data/lib/sf_cli/sf/data/helper_methods.rb

@@ -1,6 +1,7 @@
 module SfCli
   module Sf
     module Data
+      # @private
       module HelperMethods
         def prepare_record(hash) # :doc:
           hash.delete 'attributes'

data/lib/sf_cli/sf/data/query.rb

@@ -3,21 +3,17 @@ require_relative './query_helper'
 
 module SfCli::Sf::Data
   module Query
-    # get object records using SOQL.
+    # Get object records using SOQL.
+    # @param soql        [String]        SOQL
+    # @param target_org  [Symbol,String] an alias of paticular org, or username can be used
+    # @param format      [Symbol,String] get the command's raw output. human, csv, json can be available
+    # @param model_class [Class]         the object model class
+    # @param bulk        [Boolean]       use Bulk API
+    # @param timeout     [Integer]       max minutes to wait for the job complete in Bulk API mode
     #
-    # *soql* --- SOQL<br>
+    # @return [Array,[String,Array]] records or a tuple containing a flag and records
     #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
-    #
-    # *format* --- get the command's raw output. human, csv, json can be available<br>
-    #
-    # *model_class* --- the object model class<br>
-    #
-    # *bulk* --- use Bulk API<br>
-    #
-    # *timeout* --- max minutes to wait for the job complete in Bulk API mode<br>
-    #
-    # ======
+    # @example
     #   sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
     #
     #   Account = Struct.new(:Id, :Name)
@@ -32,7 +28,7 @@ module SfCli::Sf::Data
     # When using Bulk API, you get the records when the query job completes within time limit.
     # The method returns a tapple(an array), which changes its contents according to the job result.
     #
-    # ======
+    # @example
     #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true              # max wait 1 min to get result (default)
     #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 5  # max wait 5 min to get result
     #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 0  # returns immediately
@@ -40,9 +36,7 @@ module SfCli::Sf::Data
     #   rows = result   if done     # if job is completed, the result is an array of record
     #   job_id = result unless done # if job hasn't completed or it has aborted, the result is the job ID
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_unified]
-    #
-    # About querying with auto generated object model, see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_unified command reference
     #
     def query(soql, target_org: nil, format: nil, bulk: false, timeout: nil, model_class: nil)
       flags    = {
@@ -62,17 +56,15 @@ module SfCli::Sf::Data
       return_result(result, raw_output, bulk, model_class)
     end
 
-    # resume a bulk query job, which you previously started, and get records
-    #
-    # *job_id* ---  job ID you want to resume<br>
-    #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
+    # Resume a bulk query job, which you previously started, and get records
+    # @param job_id      [String]        job ID you want to resume
+    # @param target_org  [Symbol,String] an alias of paticular org, or username can be used
+    # @param format      [Symbol,String] get the command's raw output. human, csv, json can be available
+    # @param model_class [Class]         the object model class
     #
-    # *format* --- get the command's raw output. human, csv, json can be available<br>
+    # @return [Array,[String,Array]] records or a tuple containing a flag and records
     #
-    # *model_class* --- the object model class<br>
-    #
-    # ======
+    # @example
     #   # start a query job
     #   result1 = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 0  # returns immediately
     #
@@ -86,7 +78,8 @@ module SfCli::Sf::Data
     #
     #   result2 # => if done is true, this is an array of record. Otherwise it should be the Job ID.
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_resume_unified]
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_resume_unified command reference
+    #
     def query_resume(job_id:, target_org: nil, format: nil, model_class: nil)
       flags    = {
         :"bulk-query-id" => job_id,

data/lib/sf_cli/sf/data/query_helper.rb

@@ -2,6 +2,7 @@ require_relative './helper_methods'
 
 module SfCli::Sf::Data
   module Query
+    # @private
     class RegularResultAdjuster # :nodoc: all
       include ::SfCli::Sf::Data::HelperMethods
 
@@ -20,6 +21,7 @@ module SfCli::Sf::Data
       end
     end
 
+    # @private
     class BulkResultAdjuster # :nodoc: all
       include ::SfCli::Sf::Data::HelperMethods
 
@@ -42,6 +44,7 @@ module SfCli::Sf::Data
       end
     end
 
+    # @private
     class RawOutputResultAdjuster # :nodoc: all
       attr_reader :result
 

data/lib/sf_cli/sf/data/resume.rb

@@ -49,12 +49,12 @@ module SfCli::Sf::Data
     end
 
     # View the status of a bulk job.
+    # @param job_id     [String]        job ID you want to resume
+    # @param target_org [Symbol,String] an alias of paticular org, or username can be used
     #
-    # *job_id* ---  job ID you want to resume<br>
+    # @return [JobInfo] job information
     #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
-    #
-    # ======
+    # @example
     #   # start a delete job
     #   jobinfo = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv' # this returns immediately
     #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
@@ -69,9 +69,9 @@ module SfCli::Sf::Data
     # - in_progress?
     # - completed?
     #
-    # To know job status more, take a look at {the bulk API developer guide}[https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_job_states.htm]
+    # To know job status more, take a look at {https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_job_states.htm the bulk API developer guide}
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_resume_unified]
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_resume_unified command reference
     #
     def resume(job_id:, target_org: nil)
       flags = {

data/lib/sf_cli/sf/data/search.rb

@@ -1,16 +1,15 @@
 module SfCli::Sf::Data
   module Search
-    # search objects using SOSL.
+    # Search objects using SOSL.
+    # @param sosl       [String]        SOSL
+    # @param target_org [Symbol,String] an alias of paticular org, or username can be used
+    # @param format     [Symbol,String] get the command's raw output. human, csv, json can be available.
     #
-    # *sosl* --- SOSL<br>
-    #
-    # *target_org* --- an alias of paticular org, or username can be used<br>
-    #
-    # *format* --- get the command's raw output. human, csv, json can be available. *NOTE*: if you choose csv, csv files are downloaded in current directory<br>
-    #
-    # ======
-    #  # example (in irb):
+    # @return [Hash] the search result
+    # @note if you choose csv as format, csv files are downloaded in current directory
     #
+    # @example
+    #  (in irb):
     #  > sf.data.search "FIND {TIM OR YOUNG OR OIL} IN Name Fields"
     #  =>
     #  {"Lead"=>["00Q5j00000WgEuDEAV"],
@@ -24,7 +23,7 @@ module SfCli::Sf::Data
     #     "0065j00001XHJLJAA5"],
     #   "User"=>["0055j00000CcL2bAAF", "0055j00000CcL1YAAV"]}
     #
-    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_search_unified]
+    # @see https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_search_unified command reference
     #
     def search(sosl, target_org: nil, format: nil)
       flags = {