Add proper documentation to FFI::Generator and ::Task

larskanis · larskanis · commit bc99b7efa78a · 2019-05-17T22:25:42.000+02:00
diff --git a/lib/ffi/tools/generator.rb b/lib/ffi/tools/generator.rb
@@ -3,7 +3,49 @@
 
 module FFI
 
-  # @private
+  ##
+  # Generate files with C structs for FFI::Struct and C constants.
+  #
+  # == A simple example
+  #
+  # In file +zlib.rb.ffi+:
+  #   module Zlib
+  #     @@@
+  #     constants do |c|
+  #       c.include "zlib.h"
+  #       c.const :ZLIB_VERNUM
+  #     end
+  #     @@@
+  #
+  #     class ZStream < FFI::Struct
+  #
+  #       struct do |s|
+  #         s.name "struct z_stream_s"
+  #         s.include "zlib.h"
+  #
+  #         s.field :next_in,   :pointer
+  #         s.field :avail_in,  :uint
+  #         s.field :total_in,  :ulong
+  #       end
+  #       @@@
+  #     end
+  #   end
+  #
+  # Translate the file:
+  #   require "ffi/tools/generator"
+  #   FFI::Generator.new "zlib.rb.ffi", "zlib.rb"
+  #
+  # Generates the file +zlib.rb+ with constant values and offsets:
+  #   module Zlib
+  #   ZLIB_VERNUM = 4784
+  #
+  #   class ZStream < FFI::Struct
+  #     layout :next_in, :pointer, 0,
+  #            :avail_in, :uint, 8,
+  #            :total_in, :ulong, 16
+  #   end
+  #
+  # @see FFI::Generator::Task for easy integration in a Rakefile
   class Generator
 
     def initialize(ffi_name, rb_name, options = {})
diff --git a/lib/ffi/tools/generator_task.rb b/lib/ffi/tools/generator_task.rb
@@ -3,9 +3,16 @@
 require 'rake/tasklib'
 
 ##
-# Rake task that calculates C structs for FFI::Struct.
-
-# @private
+# Add Rake tasks that generate files with C structs for FFI::Struct and C constants.
+#
+# @example a simple example for your Rakefile
+#   require "ffi/tools/generator_task"
+#   # Add a task to generate my_object.rb out of my_object.rb.ffi
+#   FFI::Generator::Task.new ["my_object.rb"], cflags: "-I/usr/local/mylibrary"
+#
+# The generated files are also added to the 'clear' task.
+#
+# @see FFI::Generator for a description of the file content
 class FFI::Generator::Task < Rake::TaskLib
 
   def initialize(rb_names)
