From 1bec2c3ea436edbf497c49bfe9869b8a0a16e523 Mon Sep 17 00:00:00 2001
From: Thomas Hurst <tom@hur.st>
Date: Wed, 24 May 2017 16:33:39 +0100
Subject: [PATCH] Add some API documentation

---
 lib/capsicum.rb | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/lib/capsicum.rb b/lib/capsicum.rb
index 10272a3..49a1751 100644
--- a/lib/capsicum.rb
+++ b/lib/capsicum.rb
@@ -16,6 +16,12 @@ module Capsicum
     attach_function :cap_getmode, [IntPtr], :int
   end
 
+  # Check if we're in capability mode.
+  #
+  # @see cap_getmode(2)
+  #
+  # @return [Boolean] true if we've entered capability mode
+  # @raise [Errno::ENOTCAPABLE] - Capsicum not enabled.
   def sandboxed?
     ptr = IntPtr.new
     ret = LibC.cap_getmode(ptr)
@@ -27,6 +33,12 @@ module Capsicum
     end
   end
 
+  # Enter capability sandbox mode.
+  #
+  # @see cap_enter(2)
+  #
+  # @return [Boolean] true if we've entered capability mode.
+  # @raise [Errno::ENOTCAPABLE] - Capsicum not enabled.
   def enter!
     ret = LibC.cap_enter
 
@@ -37,6 +49,11 @@ module Capsicum
     end
   end
 
+  # Run the block within a forked process in capability mode and wait for it to
+  # complete.
+  #
+  # @yield block to run within the forked child.
+  # @return [Process::Status] exit status of the forked child.
   def within_sandbox
     return enum_for(:within_sandbox) unless block_given?