## Bug #13251

### [DOC] Add rdoc for Integer.sqrt

**Description**

Nobu, I would offer to add documentation for Integer.sqrt, feature #13219 (r57705).

I'd like to prepare a patch and eventually try to commit it myself.

I'm not sure yet when to open issues for documentation and when to simply commit; I would be glad about any feedback.

### Associated revisions

Add rdoc for Integer.sqrt

- numeric.c (rb_int_s_isqrt): [DOC] add rdoc for Integer.sqrt. [ruby-core:79762] [Bug #13251]

Add rdoc for Integer.sqrt

- numeric.c (rb_int_s_isqrt): [DOC] add rdoc for Integer.sqrt. [ruby-core:79762] [Bug #13251]

Add rdoc for Integer.sqrt

- numeric.c (rb_int_s_isqrt): [DOC] add rdoc for Integer.sqrt. [ruby-core:79762] [Bug #13251]

### History

#### Updated by nobu (Nobuyoshi Nakada) over 2 years ago

**Backport**changed from*2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: UNKNOWN*to*2.2: DONTNEED, 2.3: DONTNEED, 2.4: DONTNEED***Status**changed from*Open*to*Assigned*

Thank you, feel free to add it.

I was writing it too, but you'll make better one.

This is my draft, FYI.

```
diff --git c/NEWS i/NEWS
index 2a0413f006..8647e5e2ce 100644
--- c/NEWS
+++ i/NEWS
@@ -21,4 +21,8 @@ with all sufficient information, see the ChangeLog file or Redmine
=== Core classes updates (outstanding ones only)
+* Integer
+
+ * Integer.sqrt [Feature #13219]
+
* Regexp
* Update Onigmo 6.1.1.
Modified numeric.c
diff --git c/numeric.c i/numeric.c
index b34fb0a5f9..c827a8c7c9 100644
--- c/numeric.c
+++ i/numeric.c
@@ -5155,4 +5155,22 @@ DEFINE_INT_SQRT(BDIGIT, rb_bdigit_dbl, BDIGIT_DBL)
VALUE rb_big_isqrt(VALUE);
+/*
+ * call-seq:
+ * Integer.sqrt(x) -> Integer
+ *
+ * Returns the largest integer which does not exceed the non-negative
+ * square root of _x_. Equivalent to `Math.sqrt(x).floor`, except
+ * for that the result of the latter code may be greater than the
+ * true root when _x_ exceeds the Float precision.
+ *
+ * If _x_ is not an Integer, it is converted to an Integer first.
+ * If _x_ is negative, a Math::DomainError is raised, as well as
+ * Math.sqrt.
+ *
+ * Integer.sqrt(0) #=> 0
+ * Integer.sqrt(1) #=> 1
+ * Integer.sqrt(10) #=> 3
+ * Integer.sqrt(10**400) #=> 10**200
+ */
static VALUE
rb_int_s_isqrt(VALUE self, VALUE num)
```

#### Updated by stomar (Marcus Stollsteimer) over 2 years ago

Two clarifying questions:

Is it confirmed that using Floats will only give wrong results that are too large? __Update: no, too small also occurs.__

See e.g. the case of cube roots:

```
64 ** (1.0/3) # => 3.9999999999999996
(64 ** (1.0/3)).to_i # => 3
```

I didn't find (small) examples for sqrt similiar to this (yet?), but maybe they exist.

Does Float behave the same on all platforms and architectures?

__Update: judging from the docs for Float constants (e.g. Float::DIG), there might be differences; typical formulation: "Usually defaults to ...".__

#### Updated by stomar (Marcus Stollsteimer) over 2 years ago

FYI, here my suggestion (will commit soon, but need to read some HowTo's on how exactly that works, first):

```
diff --git a/numeric.c b/numeric.c
index b34fb0a..2400a9c 100644
--- a/numeric.c
+++ b/numeric.c
@@ -5154,6 +5154,32 @@ DEFINE_INT_SQRT(BDIGIT, rb_bdigit_dbl, BDIGIT_DBL)
VALUE rb_big_isqrt(VALUE);
+/*
+ * Document-method: Integer::sqrt
+ * call-seq:
+ * Integer.sqrt(n) -> integer
+ *
+ * Returns the integer square root of the non-negative integer +n+,
+ * i.e. the largest non-negative integer less than or equal to the
+ * square root of +n+.
+ *
+ * Integer.sqrt(0) #=> 0
+ * Integer.sqrt(1) #=> 1
+ * Integer.sqrt(24) #=> 4
+ * Integer.sqrt(25) #=> 5
+ * Integer.sqrt(10**400) #=> 10**200
+ *
+ * Equivalent to <code>Math.sqrt(n).floor</code>, except that the
+ * result of the latter code may differ from the true value
+ * due to the limited precision of floating point arithmetic.
+ *
+ * Integer.sqrt(10**46) #=> 100000000000000000000000
+ * Math.sqrt(10**46).to_i #=> 99999999999999991611392 (!)
+ *
+ * If +n+ is not an Integer, it is converted to an Integer first.
+ * If +n+ is negative, a Math::DomainError is raised.
+ */
+
static VALUE
rb_int_s_isqrt(VALUE self, VALUE num)
{
```

#### Updated by nobu (Nobuyoshi Nakada) over 2 years ago

Argument names should be marked up using `+arg+`

, or `_arg_`

?

Although I've thought it would be `_`

and there are such usage, `+`

seems major?

#### Updated by stomar (Marcus Stollsteimer) over 2 years ago

For the specific patch I tried to follow the style in the current file. Generally, I see both, and it seems `+`

is more common than `_`

(see e.g. Array).

Are there any agreed upon guidelines on documentation style? There are hints regarding __coding__ style in the Wiki, but I couldn't find any for documentation.

#### Updated by nobu (Nobuyoshi Nakada) over 2 years ago

I see, the usage is another issue in any rate.

The doc seems nice, thank you.

#### Updated by stomar (Marcus Stollsteimer) over 2 years ago

**Status**changed from*Assigned*to*Closed*

Applied in changeset r57719.

Add rdoc for Integer.sqrt

- numeric.c (rb_int_s_isqrt): [DOC] add rdoc for Integer.sqrt. [ruby-core:79762] [Bug #13251]

#### Updated by stomar (Marcus Stollsteimer) over 2 years ago

Yay, first commit...!

nobu, thanks for your patience; please give feedback if I should have done anything differently.

Add rdoc for Integer.sqrt

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@57719 b2dd03c8-39d4-4d8f-98ff-823fe69b080e