docs: make Rust docs consistent #497

DarkLord017 · 2025-01-15T18:51:05Z

Resolves #476

PR Checklist

Tests
Documentation
Changelog

netlify · 2025-01-15T18:51:22Z

✅ Deploy Preview for contracts-stylus canceled.

Name	Link
🔨 Latest commit	`7c41ab3`
🔍 Latest deploy log	https://app.netlify.com/sites/contracts-stylus/deploys/6798bc11837ea600088e2190

DarkLord017 · 2025-01-15T18:51:58Z

I also added * mark befor each event
also i have kept avery panic after events so is that ok ?

0xNeshi · 2025-01-17T20:15:08Z

@DarkLord017 you should also fix the failing CI

DarkLord017 · 2025-01-18T07:43:10Z

Okay

DarkLord017 · 2025-01-18T07:43:19Z

Okay

DarkLord017 · 2025-01-18T19:11:24Z

@DarkLord017 you should also fix the failing CI

You can review it now

contracts/src/access/control.rs

…ors(ref: OpenZeppelin#476)

…penZeppelin#476)

contracts/src/token/erc20/utils/safe_erc20.rs

bidzyyys

Great job @DarkLord017.

bidzyyys

LGTM

contracts/src/token/erc20/utils/safe_erc20.rs

DarkLord017 · 2025-01-21T18:27:24Z

Great job @DarkLord017.

Thank you !

0xNeshi · 2025-01-22T07:02:49Z

contracts/src/token/erc1155/extensions/supply.rs

+    /// NOTE: The ERC-1155 acceptance check is not performed in this function.
+    /// See [`Self::_update_with_acceptance_check`] instead.
+    ///


0xNeshi

You did a great job @DarkLord017 , most of the comments I left are related to fine-tuning the details of the original issue requirements.

Sometimes we notice the changes we want to make only once the PR is created.

0xNeshi · 2025-01-22T07:11:46Z

contracts/src/token/erc1155/extensions/uri_storage.rs

+    /// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI,
+    /// you need to do this manually.


Suggested change

/// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI,

/// you need to do this manually.

/// NOTE: To expose this function in your contract's ABI, implement it as

/// shown in the Examples section below, accepting only the `token_id`

/// parameter. The `metadata_uri` reference should come from your contract's

/// state. The implementation should forward the call to your internal

/// storage instance along with the metadata reference.

This updated NOTE section is much clearer.
All similar NOTE sections should be updated in a similar manner.

contracts/src/token/erc1155/mod.rs

contracts/src/token/erc1155/extensions/supply.rs

contracts/src/token/erc1155/mod.rs

contracts/src/token/erc721/extensions/uri_storage.rs

contracts/src/utils/cryptography/ecdsa.rs

contracts/src/utils/introspection/erc165.rs

Co-authored-by: Nenad <[email protected]>

OpenZeppelin#476)

DarkLord017 · 2025-01-25T17:39:21Z

@0xNeshi , You can review it now

should i remove the
///should not panic ?

0xNeshi · 2025-01-27T08:33:16Z

@0xNeshi , You can review it now

should i remove the ///should not panic ?

Yes

DarkLord017 · 2025-01-28T11:15:03Z

done ! @0xNeshi

0xNeshi

Looks great, I think we're close to getting this merged

0xNeshi · 2025-01-30T07:55:16Z

contracts/src/token/erc20/extensions/burnable.rs

@@ -15,26 +15,26 @@ pub trait IErc20Burnable {
    /// Destroys a `value` amount of tokens from the caller, lowering the total
    /// supply.
    ///
-    /// Relies on the `update` mechanism.
+    /// NOTE: Relies on the `update` mechanism.


@DarkLord017 you can remove these notes

0xNeshi · 2025-01-30T07:56:38Z

contracts/src/token/erc721/extensions/consecutive.rs

+    /// # Requirements
+    ///
+    /// * `token_id` must exist.
+    ///


@DarkLord017 remove all requirement sections

0xNeshi · 2025-01-30T08:01:01Z

contracts/src/token/erc20/extensions/burnable.rs

@@ -3,7 +3,7 @@
 use alloy_primitives::{Address, U256};
 use stylus_sdk::msg;

-use crate::token::erc20::{Erc20, Error};
+use crate::token::erc20::{self, Erc20, Error};


Suggested change

use crate::token::erc20::{self, Erc20, Error};

use crate::token::erc20::{self, Erc20};

Let's remove this Error import, and reference it like type Error = erc20::Error - makes it clearer that we're reusing ERC-20 errors

0xNeshi · 2025-01-30T08:01:29Z

contracts/src/token/erc721/extensions/burnable.rs

@@ -3,7 +3,7 @@
 use alloy_primitives::{Address, U256};
 use stylus_sdk::msg;

-use crate::token::erc721::{Erc721, Error};
+use crate::token::erc721::{self, Erc721, Error};


Suggested change

use crate::token::erc721::{self, Erc721, Error};

use crate::token::erc721::{self, Erc721};

Same as in previous comment

0xNeshi · 2025-01-30T08:04:32Z

contracts/src/token/erc721/extensions/metadata.rs

@@ -99,7 +102,7 @@ impl Erc721Metadata {
    ///
    /// * [`Error::NonexistentToken`] - If the token does not exist.
    ///
-    /// # Example
+    /// # Examples


There are other singular occurrences to update, do a global search in the repo

0xNeshi · 2025-01-30T08:11:27Z

contracts/src/token/erc1155/extensions/uri_storage.rs

-    /// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI,
-    /// you need to do this manually.


There are other occurrences of:

/// NOTE: In order to have [`...`] exposed in /// ABI, you need to do this manually.

You can do a global search, and update all of them

DarkLord017 and others added 2 commits January 15, 2025 23:46

ref: made rust docs consistent with format specified in OpenZeppelin#476

19c5277

Merge branch 'OpenZeppelin:main' into ConsistentDocs

96bbc2e

DarkLord017 requested review from bidzyyys, qalisander and 0xNeshi as code owners January 15, 2025 18:51

chore: fmt

adb2f80

0xNeshi assigned DarkLord017 Jan 17, 2025

DarkLord017 added 2 commits January 18, 2025 22:21

ref: Fixed failing ci errors (ref: OpenZeppelin#476)

dc25581

ref: Fixed merge conflicts in ERC1155 module

4cf43a5

0xNeshi reviewed Jan 20, 2025

View reviewed changes

contracts/src/access/control.rs Outdated Show resolved Hide resolved

contracts/src/access/control.rs Outdated Show resolved Hide resolved

bidzyyys changed the title ~~Consistent docs~~ docs: make Rust docs consistent Jan 20, 2025

DarkLord017 added 2 commits January 20, 2025 21:58

ref: Made events consistent and fixed suggested changes regarding err…

697e2ca

…ors(ref: OpenZeppelin#476)

ref: Made events consistent add description for required events(ref: O…

eeacf7e

…penZeppelin#476)

DarkLord017 requested a review from 0xNeshi January 21, 2025 11:04

bidzyyys added 7 commits January 21, 2025 13:10

docs: improve docs for access contracts

55ceec5

docs: improve docs for finance contracts.

0ce27d5

docs: improve docs for erc1155

a7cd278

docs: improve docs for erc20

5cef690

docs: improve docs for erc721

7727782

docs: improve docs for utils

9a4153b

docs: improve docs for crypto lib

62c2f6b

bidzyyys reviewed Jan 21, 2025

View reviewed changes

contracts/src/token/erc20/utils/safe_erc20.rs Outdated Show resolved Hide resolved

bidzyyys reviewed Jan 21, 2025

View reviewed changes

docs: remove redundant line

89040e2

docs: fix order in Erc721 Consecutive docs

98406d0

bidzyyys self-requested a review January 21, 2025 13:32

bidzyyys approved these changes Jan 21, 2025

View reviewed changes

contracts/src/token/erc20/utils/safe_erc20.rs Outdated Show resolved Hide resolved

docs: remove redundant line

c438661

0xNeshi reviewed Jan 22, 2025

View reviewed changes

DarkLord017 and others added 3 commits January 23, 2025 17:53

Apply suggestions from code review (ref: OpenZeppelin#476)

c297553

Co-authored-by: Nenad <[email protected]>

Merged same errors and fixed naming(ref: OpenZeppelin#476)

5412d18

Fixed linter errors for commit Merged same errors and fixed naming(ref:

873a332

OpenZeppelin#476)

DarkLord017 requested a review from 0xNeshi January 25, 2025 17:38

Removed from panic in docs (ref: OpenZeppelin#476)

7c41ab3

0xNeshi reviewed Jan 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: make Rust docs consistent #497

docs: make Rust docs consistent #497

DarkLord017 commented Jan 15, 2025 •

edited

Loading

netlify bot commented Jan 15, 2025 •

edited

Loading

DarkLord017 commented Jan 15, 2025

0xNeshi commented Jan 17, 2025

DarkLord017 commented Jan 18, 2025

DarkLord017 commented Jan 18, 2025

DarkLord017 commented Jan 18, 2025

bidzyyys left a comment

bidzyyys left a comment

DarkLord017 commented Jan 21, 2025

0xNeshi Jan 22, 2025

0xNeshi left a comment

0xNeshi Jan 22, 2025

DarkLord017 commented Jan 25, 2025

0xNeshi commented Jan 27, 2025

DarkLord017 commented Jan 28, 2025

0xNeshi left a comment

0xNeshi Jan 30, 2025

0xNeshi Jan 30, 2025

0xNeshi Jan 30, 2025

0xNeshi Jan 30, 2025

0xNeshi Jan 30, 2025

0xNeshi Jan 30, 2025

		/// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI,
		/// you need to do this manually.

-    /// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI,
-    /// you need to do this manually.
+    /// NOTE: To expose this function in your contract's ABI, implement it as
+    /// shown in the Examples section below, accepting only the `token_id`
+    /// parameter. The `metadata_uri` reference should come from your contract's
+    /// state. The implementation should forward the call to your internal
+    /// storage instance along with the metadata reference.

	use crate::token::erc20::{self, Erc20, Error};
	use crate::token::erc20::{self, Erc20};

	use crate::token::erc721::{self, Erc721, Error};
	use crate::token::erc721::{self, Erc721};

docs: make Rust docs consistent #497

Are you sure you want to change the base?

docs: make Rust docs consistent #497

Conversation

DarkLord017 commented Jan 15, 2025 • edited Loading

PR Checklist

netlify bot commented Jan 15, 2025 • edited Loading

✅ Deploy Preview for contracts-stylus canceled.

DarkLord017 commented Jan 15, 2025

0xNeshi commented Jan 17, 2025

DarkLord017 commented Jan 18, 2025

DarkLord017 commented Jan 18, 2025

DarkLord017 commented Jan 18, 2025

bidzyyys left a comment

Choose a reason for hiding this comment

bidzyyys left a comment

Choose a reason for hiding this comment

DarkLord017 commented Jan 21, 2025

Choose a reason for hiding this comment

0xNeshi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DarkLord017 commented Jan 25, 2025

0xNeshi commented Jan 27, 2025

DarkLord017 commented Jan 28, 2025

0xNeshi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DarkLord017 commented Jan 15, 2025 •

edited

Loading

netlify bot commented Jan 15, 2025 •

edited

Loading