Fix Broken Docs References (#5436)

.gitignore

@@ -37,6 +37,7 @@ npm-debug.log
 
 # docs artifacts
 docs/modules/api
+build/site
 
 # only used to package @openzeppelin/contracts
 contracts/build/

contracts/governance/Governor.sol

@@ -455,7 +455,7 @@ abstract contract Governor is Context, ERC165, EIP712, Nonces, IGovernor, IERC72
      * performed (for example adding a vault/timelock).
      *
      * NOTE: Calling this function directly will NOT check the current state of the proposal, set the executed flag to
-     * true or emit the `ProposalExecuted` event. Executing a proposal should be done using {execute} or {_execute}.
+     * true or emit the `ProposalExecuted` event. Executing a proposal should be done using {execute}.
      */
     function _executeOperations(
         uint256 /* proposalId */,

contracts/governance/README.adoc

@@ -68,7 +68,7 @@ NOTE: Functions of the `Governor` contract do not include access control. If you
 
 {{GovernorCountingFractional}}
 
-{{GovernorCountingOverride}}
+{{GovernorCountingOverridable}}
 
 {{GovernorVotes}}
 
@@ -103,7 +103,7 @@ In a governance system, the {TimelockController} contract is in charge of introd
 [[timelock-terminology]]
 ==== Terminology
 
-* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
+* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution. If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content.
 * *Operation status:*
 ** *Unset:* An operation that is not part of the timelock mechanism.
 ** *Waiting:* An operation that has been scheduled, before the timer expires.

contracts/governance/extensions/GovernorStorage.sol

@@ -50,7 +50,7 @@ abstract contract GovernorStorage is Governor {
     }
 
     /**
-     * @dev Version of {IGovernorTimelock-queue} with only `proposalId` as an argument.
+     * @dev Version of {IGovernor-queue} with only `proposalId` as an argument.
      */
     function queue(uint256 proposalId) public virtual {
         // here, using storage is more efficient than memory

contracts/governance/extensions/GovernorTimelockAccess.sol

@@ -277,7 +277,7 @@ abstract contract GovernorTimelockAccess is Governor {
     }
 
     /**
-     * @dev See {IGovernor-_cancel}
+     * @dev See {Governor-_cancel}
      */
     function _cancel(
         address[] memory targets,

contracts/proxy/utils/UUPSUpgradeable.sol

@@ -91,7 +91,6 @@ abstract contract UUPSUpgradeable is IERC1822Proxiable {
     /**
      * @dev Reverts if the execution is not performed via delegatecall or the execution
      * context is not of a proxy with an ERC-1967 compliant implementation pointing to self.
-     * See {_onlyProxy}.
      */
     function _checkProxy() internal view virtual {
         if (

contracts/token/ERC1155/IERC1155.sol

@@ -81,7 +81,7 @@ interface IERC1155 is IERC165 {
      * @dev Transfers a `value` amount of tokens of type `id` from `from` to `to`.
      *
      * WARNING: This function can potentially allow a reentrancy attack when transferring tokens
-     * to an untrusted contract, when invoking {onERC1155Received} on the receiver.
+     * to an untrusted contract, when invoking {IERC1155Receiver-onERC1155Received} on the receiver.
      * Ensure to follow the checks-effects-interactions pattern and consider employing
      * reentrancy guards when interacting with untrusted contracts.
      *
@@ -101,7 +101,7 @@ interface IERC1155 is IERC165 {
      * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {safeTransferFrom}.
      *
      * WARNING: This function can potentially allow a reentrancy attack when transferring tokens
-     * to an untrusted contract, when invoking {onERC1155BatchReceived} on the receiver.
+     * to an untrusted contract, when invoking {IERC1155Receiver-onERC1155BatchReceived} on the receiver.
      * Ensure to follow the checks-effects-interactions pattern and consider employing
      * reentrancy guards when interacting with untrusted contracts.
      *

contracts/token/ERC1155/utils/ERC1155Utils.sol

@@ -15,7 +15,7 @@ import {IERC1155Errors} from "../../../interfaces/draft-IERC6093.sol";
  */
 library ERC1155Utils {
     /**
-     * @dev Performs an acceptance check for the provided `operator` by calling {IERC1155-onERC1155Received}
+     * @dev Performs an acceptance check for the provided `operator` by calling {IERC1155Receiver-onERC1155Received}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
      * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).
@@ -50,7 +50,7 @@ library ERC1155Utils {
     }
 
     /**
-     * @dev Performs a batch acceptance check for the provided `operator` by calling {IERC1155-onERC1155BatchReceived}
+     * @dev Performs a batch acceptance check for the provided `operator` by calling {IERC1155Receiver-onERC1155BatchReceived}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
      * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).

contracts/token/ERC20/extensions/ERC4626.sol

@@ -34,7 +34,7 @@ import {Math} from "../../../utils/math/Math.sol";
  * offset (0) makes it non-profitable even if an attacker is able to capture value from multiple user deposits, as a result
  * of the value being captured by the virtual shares (out of the attacker's donation) matching the attacker's expected gains.
  * With a larger offset, the attack becomes orders of magnitude more expensive than it is profitable. More details about the
- * underlying math can be found xref:erc4626.adoc#inflation-attack[here].
+ * underlying math can be found xref:ROOT:erc4626.adoc#inflation-attack[here].
  *
  * The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued
  * to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets

contracts/token/ERC721/extensions/ERC721Consecutive.sol

@@ -159,7 +159,7 @@ abstract contract ERC721Consecutive is IERC2309, ERC721 {
     }
 
     /**
-     * @dev Used to offset the first token id in {_nextConsecutiveId}
+     * @dev Used to offset the first token id in `_nextConsecutiveId`
      */
     function _firstConsecutiveId() internal view virtual returns (uint96) {
         return 0;

contracts/token/ERC721/extensions/ERC721URIStorage.sol

@@ -52,7 +52,7 @@ abstract contract ERC721URIStorage is IERC4906, ERC721 {
     /**
      * @dev Sets `_tokenURI` as the tokenURI of `tokenId`.
      *
-     * Emits {MetadataUpdate}.
+     * Emits {IERC4906-MetadataUpdate}.
      */
     function _setTokenURI(uint256 tokenId, string memory _tokenURI) internal virtual {
         _tokenURIs[tokenId] = _tokenURI;

contracts/token/ERC721/utils/ERC721Utils.sol

@@ -15,7 +15,7 @@ import {IERC721Errors} from "../../../interfaces/draft-IERC6093.sol";
  */
 library ERC721Utils {
     /**
-     * @dev Performs an acceptance check for the provided `operator` by calling {IERC721-onERC721Received}
+     * @dev Performs an acceptance check for the provided `operator` by calling {IERC721Receiver-onERC721Received}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
      * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).

contracts/utils/Multicall.sol

@@ -13,10 +13,10 @@ import {Context} from "./Context.sol";
  * careful about sending transactions invoking {multicall}. For example, a relay address that filters function
  * selectors won't filter calls nested within a {multicall} operation.
  *
- * NOTE: Since 5.0.1 and 4.9.4, this contract identifies non-canonical contexts (i.e. `msg.sender` is not {_msgSender}).
+ * NOTE: Since 5.0.1 and 4.9.4, this contract identifies non-canonical contexts (i.e. `msg.sender` is not {Context-_msgSender}).
  * If a non-canonical context is identified, the following self `delegatecall` appends the last bytes of `msg.data`
  * to the subcall. This makes it safe to use with {ERC2771Context}. Contexts that don't affect the resolution of
- * {_msgSender} are not propagated to subcalls.
+ * {Context-_msgSender} are not propagated to subcalls.
  */
 abstract contract Multicall is Context {
     /**

contracts/utils/ShortStrings.sol

@@ -95,7 +95,7 @@ library ShortStrings {
     }
 
     /**
-     * @dev Decode a string that was encoded to `ShortString` or written to storage using {setWithFallback}.
+     * @dev Decode a string that was encoded to `ShortString` or written to storage using {toShortStringWithFallback}.
      */
     function toStringWithFallback(ShortString value, string storage store) internal pure returns (string memory) {
         if (ShortString.unwrap(value) != FALLBACK_SENTINEL) {
@@ -107,7 +107,7 @@ library ShortStrings {
 
     /**
      * @dev Return the length of a string that was encoded to `ShortString` or written to storage using
-     * {setWithFallback}.
+     * {toShortStringWithFallback}.
      *
      * WARNING: This will return the "byte length" of the string. This may not reflect the actual length in terms of
      * actual characters as the UTF-8 encoding of a single character can span over multiple bytes.

contracts/utils/Strings.sol

@@ -139,7 +139,7 @@ library Strings {
     }
 
     /**
-     * @dev Variant of {parseUint} that parses a substring of `input` located between position `begin` (included) and
+     * @dev Variant of {parseUint-string} that parses a substring of `input` located between position `begin` (included) and
      * `end` (excluded).
      *
      * Requirements:
@@ -177,7 +177,7 @@ library Strings {
     }
 
     /**
-     * @dev Implementation of {tryParseUint} that does not check bounds. Caller should make sure that
+     * @dev Implementation of {tryParseUint-string-uint256-uint256} that does not check bounds. Caller should make sure that
      * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
      */
     function _tryParseUintUncheckedBounds(
@@ -250,7 +250,7 @@ library Strings {
     }
 
     /**
-     * @dev Implementation of {tryParseInt} that does not check bounds. Caller should make sure that
+     * @dev Implementation of {tryParseInt-string-uint256-uint256} that does not check bounds. Caller should make sure that
      * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
      */
     function _tryParseIntUncheckedBounds(
@@ -287,7 +287,7 @@ library Strings {
     }
 
     /**
-     * @dev Variant of {parseHexUint} that parses a substring of `input` located between position `begin` (included) and
+     * @dev Variant of {parseHexUint-string} that parses a substring of `input` located between position `begin` (included) and
      * `end` (excluded).
      *
      * Requirements:
@@ -325,7 +325,7 @@ library Strings {
     }
 
     /**
-     * @dev Implementation of {tryParseHexUint} that does not check bounds. Caller should make sure that
+     * @dev Implementation of {tryParseHexUint-string-uint256-uint256} that does not check bounds. Caller should make sure that
      * `begin <= end <= input.length`. Other inputs would result in undefined behavior.
      */
     function _tryParseHexUintUncheckedBounds(
@@ -346,7 +346,7 @@ library Strings {
             result *= 16;
             unchecked {
                 // Multiplying by 16 is equivalent to a shift of 4 bits (with additional overflow check).
-                // This guaratees that adding a value < 16 will not cause an overflow, hence the unchecked.
+                // This guarantees that adding a value < 16 will not cause an overflow, hence the unchecked.
                 result += chr;
             }
         }
@@ -364,7 +364,7 @@ library Strings {
     }
 
     /**
-     * @dev Variant of {parseAddress} that parses a substring of `input` located between position `begin` (included) and
+     * @dev Variant of {parseAddress-string} that parses a substring of `input` located between position `begin` (included) and
      * `end` (excluded).
      *
      * Requirements:
@@ -378,7 +378,7 @@ library Strings {
 
     /**
      * @dev Variant of {parseAddress-string} that returns false if the parsing fails because the input is not a properly
-     * formatted address. See {parseAddress} requirements.
+     * formatted address. See {parseAddress-string} requirements.
      */
     function tryParseAddress(string memory input) internal pure returns (bool success, address value) {
         return tryParseAddress(input, 0, bytes(input).length);
@@ -386,7 +386,7 @@ library Strings {
 
     /**
      * @dev Variant of {parseAddress-string-uint256-uint256} that returns false if the parsing fails because input is not a properly
-     * formatted address. See {parseAddress} requirements.
+     * formatted address. See {parseAddress-string-uint256-uint256} requirements.
      */
     function tryParseAddress(
         string memory input,

contracts/utils/cryptography/EIP712.sol

@@ -109,7 +109,7 @@ abstract contract EIP712 is IERC5267 {
     }
 
     /**
-     * @dev See {IERC-5267}.
+     * @inheritdoc IERC5267
      */
     function eip712Domain()
         public

docs/modules/ROOT/pages/crowdsales.adoc

@@ -1,11 +0,0 @@
-= Crowdsales
-
-All crowdsale-related contracts were removed from the OpenZeppelin Contracts library on the https://forum.openzeppelin.com/t/openzeppelin-contracts-v3-0-beta-release/2256[v3.0.0 release] due to both a decline in their usage and the complexity associated with migrating them to Solidity v0.6.
-
-They are however still available on the v2.5 release of OpenZeppelin Contracts, which you can install by running:
-
-```console
-$ npm install @openzeppelin/contracts@v2.5
-```
-
-Refer to the https://docs.openzeppelin.com/contracts/2.x/crowdsales[v2.x documentation] when working with them.

docs/modules/ROOT/pages/drafts.adoc

@@ -1,19 +0,0 @@
-= Drafts
-
-All draft contracts were either moved into a different directory or removed from the OpenZeppelin Contracts library on the https://forum.openzeppelin.com/t/openzeppelin-contracts-v3-0-beta-release/2256[v3.0.0 release].
-
-* `ERC20Migrator`: removed.
-* xref:api:token/ERC20.adoc#ERC20Snapshot[`ERC20Snapshot`]: moved to `token/ERC20`.
-* `ERC20Detailed` and `ERC1046`: removed.
-* `TokenVesting`: removed. Pending a replacement that is being discussed in https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1214[`#1214`].
-* xref:api:utils.adoc#Counters[`Counters`]: moved to xref:api:utils.adoc[`utils`].
-* xref:api:utils.adoc#Strings[`Strings`]: moved to xref:api:utils.adoc[`utils`].
-* xref:api:utils.adoc#SignedSafeMath[`SignedSafeMath`]: moved to xref:api:utils.adoc[`utils`].
-
-Removed contracts are still available on the v2.5 release of OpenZeppelin Contracts, which you can install by running:
-
-```console
-$ npm install @openzeppelin/contracts@v2.5
-```
-
-Refer to the xref:2.x@contracts:api:drafts.adoc[v2.x documentation] when working with them.

docs/modules/ROOT/pages/governance.adoc

@@ -52,7 +52,7 @@ If your project already has a live token that does not include ERC20Votes and is
 include::api:example$governance/MyTokenWrapped.sol[]
 ```
 
-NOTE: The only other source of voting power available in OpenZeppelin Contracts currently is xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]. ERC-721 tokens that don't provide this functionality can be wrapped into a voting tokens using a combination of xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`] and xref:api:token/ERC721Wrapper.adoc#ERC721Wrapper[`ERC721Wrapper`].
+NOTE: The only other source of voting power available in OpenZeppelin Contracts currently is xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]. ERC-721 tokens that don't provide this functionality can be wrapped into a voting tokens using a combination of xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`] and xref:api:token/ERC721.adoc#ERC721Wrapper[`ERC721Wrapper`].
 
 NOTE: The internal clock used by the token to store voting balances will dictate the operating mode of the Governor contract attached to it. By default, block numbers are used. Since v4.9, developers can override the xref:api:interfaces.adoc#IERC6372[IERC6372] clock to use timestamps instead of block numbers.
 

docs/templates/contract.hbs

@@ -2,6 +2,10 @@
 :{{name}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]]
 {{/each}}
 
+{{#each functions}}
+:{{fullname}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]]
+{{/each}}
+
 [.contract]
 [[{{anchor}}]]
 === `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link]

docs/templates/properties.js

@@ -17,6 +17,22 @@ module.exports.anchor = function anchor({ item, contract }) {
   return res;
 };
 
+module.exports.fullname = function fullname({ item }) {
+  let res = '';
+  res += item.name;
+  if ('parameters' in item) {
+    const signature = item.parameters.parameters.map(v => v.typeName.typeDescriptions.typeString).join(',');
+    res += slug('(' + signature + ')');
+  }
+  if (isNodeType('VariableDeclaration', item)) {
+    res += '-' + slug(item.typeName.typeDescriptions.typeString);
+  }
+  if (res.charAt(res.length - 1) === '-') {
+    return res.slice(0, -1);
+  }
+  return res;
+};
+
 module.exports.inheritance = function ({ item, build }) {
   if (!isNodeType('ContractDefinition', item)) {
     throw new Error('used inherited-items on non-contract');