From 6fe3e9e48877d4a7d373f8db476f0855f69b605f Mon Sep 17 00:00:00 2001
From: zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Sun, 28 Apr 2013 00:51:46 +0000
Subject: * object.c: Documentation for taint and trust [Bug #8162]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@40508 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog |  4 ++++
 object.c  | 47 +++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b3b3252ee9..6e28b0fcd6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Sun Apr 28 09:50:00 2013  Zachary Scott  <zachary@zacharyscott.net>
+
+	* object.c: Documentation for taint and trust [Bug #8162]
+
 Sun Apr 28 09:40:00 2013  Zachary Scott  <zachary@zacharyscott.net>
 
 	* README.EXT: Copy note from r40505 for rb_sprintf() [Bug #7982]
diff --git a/object.c b/object.c
index 73c6c57e46..1078995e03 100644
--- a/object.c
+++ b/object.c
@@ -844,7 +844,9 @@ rb_obj_dummy(void)
  *  call-seq:
  *     obj.tainted?    -> true or false
  *
- *  Returns <code>true</code> if the object is tainted.
+ *  Returns whether the object is tainted.
+ *
+ *  See #taint for more information.
  */
 
 VALUE
@@ -859,9 +861,20 @@ rb_obj_tainted(VALUE obj)
  *  call-seq:
  *     obj.taint -> obj
  *
- *  Marks <i>obj</i> as tainted---if the <code>$SAFE</code> level is
- *  set appropriately, many method calls which might alter the running
- *  programs environment will refuse to accept tainted strings.
+ *  Mark the object as tainted.
+ *
+ *  To check whether an object is tainted, use #tainted?
+ *
+ *  Objects that are marked as tainted will be restricted from various built-in
+ *  methods. This is to prevent insecure data, such as command-line arguments
+ *  or strings read from Kernel#gets, from inadvertently compromising the users
+ *  system.
+ *
+ *  You should only untaint a tainted object if your code has inspected it and
+ *  determined that it is safe. To do so use #untaint
+ *
+ *  In $SAFE level 3 and 4, all objects are both tainted and untrusted, and the
+ *  trust and taint methods will both raise a SecurityError exception.
  */
 
 VALUE
@@ -880,7 +893,9 @@ rb_obj_taint(VALUE obj)
  *  call-seq:
  *     obj.untaint    -> obj
  *
- *  Removes the taint from <i>obj</i>.
+ *  Removes the tainted mark from the object.
+ *
+ *  See #taint for more information.
  */
 
 VALUE
@@ -898,7 +913,9 @@ rb_obj_untaint(VALUE obj)
  *  call-seq:
  *     obj.untrusted?    -> true or false
  *
- *  Returns <code>true</code> if the object is untrusted.
+ *  Returns whether the object is untrusted.
+ *
+ *  See #untrust for more information.
  */
 
 VALUE
@@ -913,7 +930,19 @@ rb_obj_untrusted(VALUE obj)
  *  call-seq:
  *     obj.untrust -> obj
  *
- *  Marks <i>obj</i> as untrusted.
+ *  Mark the object as untrusted.
+ *
+ *  An untrusted object is not allowed to modify any trusted objects. To check
+ *  whether an object is trusted, use #untrusted?
+ *
+ *  Any object created by untrusted code is marked as both tainted and
+ *  untrusted. See #taint for more information.
+ *
+ *  You should only trust an untrusted object if your code has inspected it and
+ *  determined that it is safe. To do so use #trust
+ *
+ *  In $SAFE level 3 and 4, all objects are both tainted and untrusted, and the
+ *  trust and taint methods will both raise a SecurityError exception.
  */
 
 VALUE
@@ -932,7 +961,9 @@ rb_obj_untrust(VALUE obj)
  *  call-seq:
  *     obj.trust    -> obj
  *
- *  Removes the untrusted mark from <i>obj</i>.
+ *  Removes the untrusted mark from the object.
+ *
+ *  See #untrust for more information.
  */
 
 VALUE
-- 
cgit v1.2.3