Solc --devdoc --userdoc generator does not work with @openzeppelin imports

Archive SDK
1

Hi,
I just installed solc with homebrew on macOS Catalina because I want to make use of the Documentation Output generator solc --userdoc --devdoc . (And because I was to lazy to get openzeppelin’s solidity-docgen working. The command seems to be broken/unlinked:
image

Back to the solc problem:
However, solc seems to have problems with the @openzeppelin import statements.

image
image.png2648×492 94.2 KB

not found: File not found: Does anybody have any quick fixes on how solc can find those @openzeppelin/ files?

Best,

Luis

1 Like
2

Hi @gitpusha,

My suggestion would be to use solidity-docgen. :smile:

I haven’t used solc direct, so hopefully someone in the community can advise.

1 Like
3

Hi @gitpusha,

Were you able to find how to use @openzeppelin with solc?
I tried remappings but haven’t got the syntax correct.

To generate a document with solidity-docgen you can do the following:
Install:

npm install solidity-docgen

Run (using contracts in the contracts directory):

npx solidity-docgen --solc-settings  "{remappings: ['@openzeppelin/contracts-ethereum-package=$PWD/node_modules/@openzeppelin/contracts-ethereum-package','@openzeppelin/upgrades=$PWD/node_modules/@openzeppelin/upgrades']}"

Sample token:

Token.sol

pragma solidity ^0.5.0;

import "@openzeppelin/upgrades/contracts/Initializable.sol";

import "@openzeppelin/contracts-ethereum-package/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts-ethereum-package/contracts/token/ERC20/ERC20Detailed.sol";

/**
 * @title SimpleToken
 * @dev Very simple ERC20 Token example, where all tokens are pre-assigned to the creator.
 * Note they can later distribute these tokens as they wish using `transfer` and other
 * `ERC20` functions.
 */
contract Token is Initializable, ERC20, ERC20Detailed {

    /**
     * @dev initialize that gives msg.sender all of existing tokens.
     */
    function initialize(address sender) public initializer {
        ERC20Detailed.initialize("Token", "TKN", 18);
        _mint(sender, 1000000 * (10 ** uint256(decimals())));
    }
}
4

Hey there! I understand that solidity-docgen is a bit hard to use right now due to lack of documentation, but I’m willing to help you get it set up and customized. It fixes many shortcomings of solc’s native natspec support and gives you a lot of flexibility to achieve whatever kind of documentation you want. The output is completely customizable using Handlebars templates.

@abcoathup’s instructions should get you started. If you want to do any sort of customization of the output, let me know and I’ll guide you through it.

The only thing I’d add to @abcoathup is that it’s possible to use a shorter command since all of our packages share the @openzeppelin prefix:

npx solidity-docgen --solc-settings  "{remappings: ['@openzeppelin=$PWD/node_modules/@openzeppelin']}"

This is now in the readme.

1 Like
5

Thank you very much for stepping in and helping out. I will revisit this topic soon, and report back to you.

1 Like
6

Added this to my package.json’s scripts {} object so all I need to do is npm run docs

“doc”: “npx solidity-docgen --solc-settings “{remappings: [’@openzeppelin=$PWD/node_modules/@openzeppelin’]}””

2 Likes
7

Hi everyone. The latest solidity-docgen includes out of the box support for dependencies. I haven’t tested it extensively myself so please give it a shot and let me know how it goes.

1 Like