Skip to content

Simple docs update request #5879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
0xpessimist opened this issue Feb 28, 2025 · 6 comments
Closed

Simple docs update request #5879

0xpessimist opened this issue Feb 28, 2025 · 6 comments

Comments

@0xpessimist
Copy link

I opened a PR on stacks-network/docs to update the documentation (here: stacks-network/docs#1710), I was asked to open an issue here because it was auto-generated. That documentation for the pow function appears to come from:

const POW_API: SimpleFunctionAPI = SimpleFunctionAPI {
name: None,
snippet: "pow ${1:expr-1} ${2:expr-2}",
signature: "(pow i1 i2)",
description: "Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error.
Note: Corner cases are handled with the following rules:
* if both `i1` and `i2` are `0`, return `1`
* if `i1` is `1`, return `1`
* if `i1` is `0`, return `0`
* if `i2` is `1`, return `i1`
* if `i2` is negative or greater than `u32::MAX`, throw a runtime error",
example: "(pow 2 3) ;; Returns 8
(pow 2 2) ;; Returns 4
(pow 7 1) ;; Returns 7
"
};

And I want to add;

  • if i2 is 0, return 1
@wileyj
Copy link
Collaborator

wileyj commented Feb 28, 2025

@obycode i think the question here is if @0xpessimist is correct in that the text is missing from the source code (and downstream in the documentation), and if it needs to be added. if true, we can put together a PR to address.

@obycode
Copy link
Contributor

obycode commented Feb 28, 2025

That is correct, but is not a corner case, so I don't think it needs to be added. Actually, I might remove one of the existing bullet points, "if i2 is 1, return i1", because I don't think that is a corner case either. I see in the history that I added that bullet point originally, but now I'm not seeing why it is a corner case like the others.

@obycode
Copy link
Contributor

obycode commented Feb 28, 2025

By "corner case", what we mean is something where the code may operate differently from what you would expect mathematically. The case when i2 is 0, return 1 would be the standard mathematical result.

@0xpessimist
Copy link
Author

Yes, I felt the need to add this too because "if i2 is 1, return i1" was also not a corner case. It makes more sense to remove cases that are not corner cases

@wileyj
Copy link
Collaborator

wileyj commented Mar 1, 2025

Yes, I felt the need to add this too because "if i2 is 1, return i1" was also not a corner case. It makes more sense to remove cases that are not corner cases

since you found this @0xpessimist , could you put together the pr with brice's suggestion? we can retcon the docs until the change is released as well

wileyj added a commit to wileyj/stacks-core that referenced this issue Mar 13, 2025
- originally proposed by `0xpessimist` in stacks-network#5879 via stacks-network/docs#1710
@stacks-network stacks-network deleted a comment May 1, 2025
@obycode
Copy link
Contributor

obycode commented May 7, 2025

This was resolved in #5923.

@obycode obycode closed this as completed May 7, 2025
@github-project-automation github-project-automation bot moved this from Status: 🆕 New to Status: ✅ Done in Stacks Core Eng May 7, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Status: ✅ Done
Development

No branches or pull requests

3 participants