Simple docs update request

[0xpessimist]

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:

stacks-core/clarity/src/vm/docs/mod.rs

Lines 493 to 508 in 2caa9bf

	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]

@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]

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]

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]

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]

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

[obycode]

This was resolved in #5923.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.