docs

.gitignore

@@ -1,3 +1,5 @@
 *.gem
 /coverage/
 /libcs/
+/doc/
+/.yardoc/

lib/one_gadget/abi.rb

@@ -3,7 +3,9 @@ module OneGadget
   module ABI
     # Define class methods here.
     module ClassMethods
+      # Registers in i386.
       LINUX_X86_32 = %w(eax ebx ecx edx edi esi ebp esp).freeze
+      # Registers in x86_64/
       LINUX_X86_64 = LINUX_X86_32 + %w(rax rbx rcx rdx rdi rsi rbp rsp) + 7.upto(15).map { |i| "r#{i}" }
       # Registers' name in amd64.
       # @return [Array<String>] List of registers.

lib/one_gadget/emulators/i386.rb

@@ -6,6 +6,7 @@ module OneGadget
     # Emulator of amd64 instruction set.
     class I386 < X86
       class << self
+        # Yap, bits.
         def bits
           32
         end

lib/one_gadget/emulators/lambda.rb

@@ -3,10 +3,10 @@ require 'one_gadget/helper'
 module OneGadget
   module Emulators
     # A {Lambda} object can be:
-    # 1. {String} # variable name
+    # 1. +String+ (variable name)
-    # 2. {Numeric}
+    # 2. +Numeric+
-    # 3. {Lambda} + {Numeric}
+    # 3. {Lambda} + +Numeric+
-    # 4. dereference {Lambda}
+    # 4. dereferenced {Lambda}
     class Lambda
       attr_accessor :obj # @return [String, Lambda] The object currently related to.
       attr_accessor :immi # @return [Integer] The immidiate value currently added.
@@ -49,6 +49,7 @@ module OneGadget
 
       # Decrease dreference count with 1.
       # @return [void]
+      # @raise [ArgumentError] When this object cannot be referenced anymore.
       def ref!
         raise ArgumentError, 'Cannot reference anymore!' if @deref_count <= 0
         @deref_count -= 1
@@ -86,14 +87,18 @@ module OneGadget
       end
 
       class << self
-        # Target: parse something like +[rsp+0x50]+ into a {Lambda} object.
+        # Target: parse things like <tt>[rsp+0x50]</tt> into a {Lambda} object.
         # @param [String] arg
         # @param [Hash{String => Lambda}] predefined
+        #   Predfined values.
         # @return [OneGadget::Emulators::Lambda, Integer]
         #   If +arg+ contains number only, return it.
         #   Otherwise, return a {Lambda} object.
         # @example
-        #   parse('[rsp+0x50]') #=> #<Lambda @obj='rsp', @immi=80, @deref_count=1>
+        #   obj = parse('[rsp+0x50]')
+        #   #=> #<Lambda @obj='rsp', @immi=80, @deref_count=1>
+        #   parse('obj+0x30', predefined: { 'obj' => obj }).to_s
+        #   #=> '[rsp+0x50]+0x30'
         def parse(arg, predefined: {})
           deref_count = 0
           if arg[0] == '[' # a little hack because there should nerver something like +[[rsp+1]+2]+ to parse.

lib/one_gadget/fetchers/base.rb

@@ -2,7 +2,7 @@ require 'shellwords'
 
 module OneGadget
   module Fetcher
-    # define common methods for gadget fetchers.
+    # Define common methods for gadget fetchers.
     class Base
       # The absolute path of glibc.
       # @return [String] The filename.
@@ -19,6 +19,12 @@ module OneGadget
       end
 
       # Fetch candidates that end with call exec*.
+      #
+      # Give a block to filter gadget candidates.
+      # @yieldparam [String] cand
+      #   Is this candidate valid?
+      # @yieldreturn [Boolean]
+      #   True for valid.
       # @return [Array<String>]
       #   Each +String+ returned is multi-lines of assembly code.
       def candidates(&block)

lib/one_gadget/gadget.rb

@@ -40,7 +40,9 @@ module OneGadget
 
     # Define class methods here.
     module ClassMethods
+      # Path to the pre-build files.
       BUILDS_PATH = File.join(__dir__, 'builds').freeze
+      # Cache.
       BUILDS = Hash.new { |h, k| h[k] = [] }
       # Get gadgets from pre-defined corpus.
       # @param [String] build_id Desired build id.

lib/one_gadget/helper.rb

@@ -9,6 +9,7 @@ require 'one_gadget/logger'
 module OneGadget
   # Define some helpful methods here.
   module Helper
+    # Format of build-id, 40 hex numbers.
     BUILD_ID_FORMAT = /[0-9a-f]{40}/
     # Define class methods here.
     module ClassMethods
@@ -125,7 +126,7 @@ module OneGadget
       end
 
       # Fetch the file archiecture of +file+.
-      # @param [String] The target ELF filename.
+      # @param [String] file The target ELF filename.
       # @return [String]
       #   Only supports :amd64, :i386 now.
       def architecture(file)

lib/one_gadget/version.rb

@@ -1,3 +1,4 @@
 module OneGadget
+  # Current gem version.
   VERSION = '1.3.4.1'.freeze
 end