doc: add and update doc for `numbers.jl` #201

inkydragon · 2025-11-20T15:52:57Z

#187

Add new doc for

Update doc for

catalannum
lobbnum
narayana
lassallenum
stirlings1
stirlings2

Add more tests for

catalannum
fibonaccinum
lassallenum

codecov · 2025-11-20T16:00:04Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.17%. Comparing base (b808ce2) to head (45b3e02).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #201   +/-   ##
=======================================
  Coverage   97.17%   97.17%           
=======================================
  Files           8        8           
  Lines         813      813           
=======================================
  Hits          790      790           
  Misses         23       23

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR enhances the documentation for special number functions in numbers.jl by adding comprehensive docstrings with mathematical formulas, examples, and references, while also expanding test coverage.

Key changes:

Added new documentation with examples and references for bellnum, fibonaccinum, jacobisymbol, legendresymbol, and lucasnum
Updated documentation for catalannum, lobbnum, narayana, lassallenum, stirlings1, and stirlings2 with mathematical formulas, detailed examples, and DLMF/Wikipedia references
Expanded test coverage for catalannum, fibonaccinum, and lassallenum with additional test cases and edge cases
Improved error messages by adding descriptive text to DomainError exceptions (e.g., "n must be nonnegative")

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 13 comments.

File	Description
src/numbers.jl	Added comprehensive documentation for 5 functions and updated documentation for 6 existing functions with mathematical formulas, examples, and references; improved error messages with descriptive text
test/numbers.jl	Reorganized tests by moving `bellnum` tests to the beginning; added extensive test coverage for `catalannum`, `fibonaccinum`, and `lassallenum` with edge cases and large values

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-08T14:53:02Z

src/numbers.jl

+julia> n=9; stirlings1(n, 1) == factorial(n-1)
+true
+
+julia> n=233; stirlings1(n, n-1) == binomial(n,2)


Missing spaces around assignment operator. Should be n = 233 instead of n=233 to follow Julia style conventions.

Suggested change

julia> n=9; stirlings1(n, 1) == factorial(n-1)

true

julia> n=233; stirlings1(n, n-1) == binomial(n,2)

julia> n = 9; stirlings1(n, 1) == factorial(n-1)

true

julia> n = 233; stirlings1(n, n-1) == binomial(n,2)

Copilot · 2025-12-08T14:53:02Z

src/numbers.jl

+julia> n=6; sum(stirlings2(6, k) for k in 0:6) == bellnum(n)
+true
+
+julia> [stirlings2(n,k) for n in 1:6, k in 1:6]


Missing spaces after commas in function call. Should be [stirlings2(n, k) for n in 1:6, k in 1:6] to be consistent with Julia style conventions.

Suggested change

julia> [stirlings2(n,k) for n in 1:6, k in 1:6]

julia> [stirlings2(n, k) for n in 1:6, k in 1:6]

Copilot · 2025-12-08T14:53:03Z

src/numbers.jl

+julia> n=9; stirlings1(n, 1) == factorial(n-1)
+true
+
+julia> n=233; stirlings1(n, n-1) == binomial(n,2)


Missing space after comma in function call. Should be binomial(n, 2) to be consistent with Julia style conventions used elsewhere in the documentation.

Suggested change

julia> n=233; stirlings1(n, n-1) == binomial(n,2)

julia> n=233; stirlings1(n, n-1) == binomial(n, 2)

Copilot · 2025-12-08T14:53:03Z

src/numbers.jl

+julia> stirlings2(0, 0)
+1
+
+julia> n=233; stirlings2(n, 0) == 0  # n > 0


Missing spaces around assignment operator. Should be n = 233 instead of n=233 to follow Julia style conventions.

Copilot · 2025-12-08T14:53:03Z

src/numbers.jl

+julia> stirlings2(0, 1)
+0
+
+julia> n=13; stirlings2(n, 1) == stirlings2(n, n) == 1  # n > 0


Missing spaces around assignment operator. Should be n = 13 instead of n=13 to follow Julia style conventions.

Copilot · 2025-12-08T14:53:04Z

src/numbers.jl

 end

 """
    narayana(n,k)


Missing space after comma in function signature documentation. Should be narayana(n, k) to match the updated style used in other function signatures in this PR (e.g., lobbnum(m, n) on line 100).

Suggested change

narayana(n,k)

narayana(n, k)

Copilot · 2025-12-08T14:53:05Z

src/numbers.jl

        n = BigInt(bn)
        k = BigInt(bk)
    end
    div(binomial(n, k)*binomial(n, k - 1) , n)


Extra space before comma. Should be binomial(n, k - 1), n) (remove the space before the comma after k - 1).

Suggested change

div(binomial(n, k)*binomial(n, k - 1) , n)

div(binomial(n, k)*binomial(n, k - 1), n)

Copilot · 2025-12-08T14:53:05Z

src/numbers.jl

+julia> stirlings1(6, 3, true)
+-225
+
+julia> [stirlings1(n,k,true) for n in 1:6, k in 1:6]


Missing spaces after commas in function call. Should be [stirlings1(n, k, true) for n in 1:6, k in 1:6] to be consistent with Julia style conventions.

Suggested change

julia> [stirlings1(n,k,true) for n in 1:6, k in 1:6]

julia> [stirlings1(n, k, true) for n in 1:6, k in 1:6]

Copilot · 2025-12-08T14:53:05Z

test/numbers.jl


      # lassalle
+      # https://oeis.org/A180874
+      @test lassallenum.(1:10) == [1,1,5,56,1092,32670,1387815,79389310,5882844968,548129834616]


Missing spaces after commas in the array. Should be [1, 1, 5, 56, 1092, 32670, 1387815, 79389310, 5882844968, 548129834616] to be consistent with Julia style conventions and other tests in this file (e.g., line 24, 32).

Suggested change

@test lassallenum.(1:10) == [1,1,5,56,1092,32670,1387815,79389310,5882844968,548129834616]

@test lassallenum.(1:10) == [1, 1, 5, 56, 1092, 32670, 1387815, 79389310, 5882844968, 548129834616]

Copilot · 2025-12-08T14:53:06Z

src/numbers.jl

+julia> stirlings1(5, 5)  # s(n, n) = 1
+1
+
+julia> n=9; stirlings1(n, 1) == factorial(n-1)


Missing space after semicolon in compound statement. Should be n=9; stirlings1(n, 1) == factorial(n-1) → n = 9; stirlings1(n, 1) == factorial(n-1) to follow Julia style conventions (spaces around assignment operators).

Suggested change

julia> n=9; stirlings1(n, 1) == factorial(n-1)

julia> n = 9; stirlings1(n, 1) == factorial(n-1)

depial

Some small suggestions/options and a couple of questions.

I feel like I'm ignorant to how the end docstring gets rendered. Specifically, I don't know if double back-ticks is processed the same as $ in standard LaTeX. Also, the double backslash is new to me.

Any question in my review are genuine (rather than rhetorical), so please feel free to answer them if you have time since I'm interested in the answer.

As a final note: I went ahead an reran all the code examples and checked the links, with everything looking good on those two points.

depial · 2025-12-14T19:04:03Z

src/numbers.jl

-Compute the ``n``th Catalan number.
+Compute the ``n``th Catalan number given by:
+```math
+C_n = \\frac{1}{n+1} \\binom{2n}{n}


Does the double backslash render the LaTeX properly? It doesn't here in GitHub markdown, and I'm not used to that when I use LaTeX, so I thought I'd mention it.
Double backslash:
$$C_n = \\frac{1}{n+1} \\binom{2n}{n}$$
Single backslash:
$$C_n = \frac{1}{n+1} \binom{2n}{n}$$

depial · 2025-12-14T19:06:38Z

src/numbers.jl

+Compute the Lobb number `L(m,n)`, or the generalised Catalan number given by:
+```math
+L_{m,n} = \\frac{2m+1}{m+n+1} \\binom{2n}{m+n}
+```
+For `m = 0`, we get the ``n``-th Catalan number.


L(m,n) could probably be excluded here, since it's not the name of the function and it is defined mathematically below using subscripts. If it's kept, maybe a space could be inserted to match function style: L(m, n)

Also: "generalised" is British English and "generalized" is American English (if there is a preference) and n-th Catalan number is written above in catalannum(n) as nth Catalan number (so minus the dash).

With the above changes, it could look like (using single backslashes):

Compute the Lobb number, aka the generalized Catalan number, given by:
$$L_{m,n} = \frac{2m+1}{m+n+1} \binom{2n}{m+n}$$
For m = 0, we get the nth Catalan number.

depial · 2025-12-14T19:11:43Z

src/numbers.jl


-Compute the Narayana number `N(n,k)` given by ``\\frac{1}{n}\\binom{n}{k}\\binom{n}{k-1}``
-Wikipedia : https://en.wikipedia.org/wiki/Narayana_number
+Compute the Narayana number `N(n,k)` given by ``\\frac{1}{n}\\binom{n}{k}\\binom{n}{k-1}``,


Same comment concerning N(n,k) as above with L(m,n)

depial · 2025-12-14T19:29:51Z

src/numbers.jl

-    stirlings1(n::Integer, k::Integer)
+    stirlings1(n::Integer, k::Integer, signed::Bool=false)
+
+Compute the Stirling number of the first kind, ``s(n,k)``, for non-negative `n`.


s(n,k) is in double back-ticks, whereas the other instances of functions like this have been in single back-ticks.

depial · 2025-12-14T19:33:53Z

src/numbers.jl

    stirlings2(n::Integer, k::Integer)

-Compute the Stirling number of the second kind, `S(n,k)`.
+Compute the Stirling number of the second kind, ``S(n,k)``, for non-negative `n`.


Mentioning the double back-ticks vs single back-ticks again.

depial · 2025-12-14T19:36:23Z

src/numbers.jl

+julia> n=13; stirlings2(n, 1) == stirlings2(n, n) == 1  # n > 0
+true
+
+julia> n=6; [stirlings2(6, k) for k in 0:6]


n is not used int the comprehension. Was it suppose to be:

julia> n=6; [stirlings2(n, k) for k in 0:6]

depial · 2025-12-14T19:38:03Z

src/numbers.jl

+ 15
+  1
+
+julia> n=6; sum(stirlings2(6, k) for k in 0:6) == bellnum(n)


Again, unsure if the n should be used in stirlings2(n, k) while it is being used in bellnum(n).

depial · 2025-12-14T19:45:00Z

test/numbers.jl

+      @test fibonaccinum(92) == big"7540113804746346429"
+      @test fibonaccinum(92) < typemax(Int64) < fibonaccinum(93)
      @test fibonaccinum(101) == parse(BigInt, "573147844013817084101")


Is there a reason the forms big"7540113804746346429" and parse(BigInt, "7540113804746346429") are being used?

I think the former might be more performant, but I'm unsure if there is some other reason for testing purposes to use both.

inkydragon added 15 commits November 20, 2025 23:57

bellnum: improve error msg

4d277f3

doc: add doc and examples for bellnum

655fdfa

test: update tests for bellnum

e60c4da

doc: add doc and examples for catalannum

c125e16

test: update tests for catalannum

ac3abb6

lobbnum: improve error msg

7588066

doc: add doc and examples for lobbnum

b5b8570

doc: add doc and examples for fibonaccinum

036533d

test: update tests for fibonaccinum

ee909e2

doc: add doc and examples for jacobisymbol

e874697

doc: add doc and examples for legendresymbol

f7eed5f

doc: add doc and examples for lucasnum

58a84aa

doc: add doc and examples for stirlings1

f9d7bd1

doc: add doc and examples for stirlings2

fbb188e

doc: update doc for Stirling number

fd4f82d

inkydragon force-pushed the doc-numbers branch from a1d5802 to fd4f82d Compare November 20, 2025 15:58

inkydragon added the doc documentation label Nov 20, 2025

inkydragon added this to the v1.1.0 milestone Nov 20, 2025

inkydragon mentioned this pull request Nov 20, 2025

Add docs for all exported functions #187

Open

14 tasks

inkydragon added 3 commits November 21, 2025 00:14

doc: add examples for lassallenum

f434e08

test: add tests for lassallenum

3e79e6d

doc: add examples for narayana

5a7eb67

inkydragon marked this pull request as ready for review November 22, 2025 07:44

inkydragon requested a review from Copilot December 8, 2025 14:46

Copilot started reviewing on behalf of inkydragon December 8, 2025 14:47 View session

Copilot AI reviewed Dec 8, 2025

View reviewed changes

inkydragon mentioned this pull request Dec 8, 2025

permutations iteration regression in version 1.0.3 #194

Closed

inkydragon removed this from the v1.1.0 milestone Dec 12, 2025

Merge branch 'master' into doc-numbers

45b3e02

depial reviewed Dec 14, 2025

View reviewed changes

	julia> [stirlings2(n,k) for n in 1:6, k in 1:6]
	julia> [stirlings2(n, k) for n in 1:6, k in 1:6]

	julia> n=233; stirlings1(n, n-1) == binomial(n,2)
	julia> n=233; stirlings1(n, n-1) == binomial(n, 2)

	div(binomial(n, k)*binomial(n, k - 1) , n)
	div(binomial(n, k)*binomial(n, k - 1), n)

	julia> [stirlings1(n,k,true) for n in 1:6, k in 1:6]
	julia> [stirlings1(n, k, true) for n in 1:6, k in 1:6]

	@test lassallenum.(1:10) == [1,1,5,56,1092,32670,1387815,79389310,5882844968,548129834616]
	@test lassallenum.(1:10) == [1, 1, 5, 56, 1092, 32670, 1387815, 79389310, 5882844968, 548129834616]

	julia> n=9; stirlings1(n, 1) == factorial(n-1)
	julia> n = 9; stirlings1(n, 1) == factorial(n-1)

doc: add and update doc for numbers.jl #201

Are you sure you want to change the base?

doc: add and update doc for numbers.jl #201

Uh oh!

Conversation

inkydragon commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

depial left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

doc: add and update doc for `numbers.jl` #201

doc: add and update doc for `numbers.jl` #201

inkydragon commented Nov 20, 2025 •

edited

Loading

codecov bot commented Nov 20, 2025 •

edited

Loading

depial left a comment •

edited

Loading