开源项目 primitive-dodoc 常见问题解决方案

开源项目 primitive-dodoc 常见问题解决方案

primitive-dodoc ☄️ Zero-config Hardhat plugin to generate documentation for all your Solidity contracts. 项目地址: https://gitcode.com/gh_mirrors/pr/primitive-dodoc

项目基础介绍和主要编程语言

项目名称: primitive-dodoc
项目简介: primitive-dodoc 是一个零配置的 Hardhat 插件，旨在为所有 Solidity 合约生成文档。它支持最新的 Solidity 版本，并且可以自动生成 Markdown 格式的文档。
主要编程语言: Solidity、JavaScript/TypeScript

新手在使用这个项目时需要特别注意的3个问题及详细解决步骤

问题1: 安装插件时出现依赖冲突

问题描述: 新手在安装 @primitivefi/hardhat-dodoc 插件时，可能会遇到依赖冲突，导致安装失败。

解决步骤:

1. 检查依赖版本: 确保你的 Hardhat 项目使用的依赖版本与 @primitivefi/hardhat-dodoc 插件兼容。
2. 清理缓存: 运行以下命令清理 npm 或 yarn 的缓存：
   • 对于 npm: npm cache clean --force
   • 对于 yarn: yarn cache clean
3. 重新安装: 重新运行安装命令：
   • 对于 yarn: yarn add @primitivefi/hardhat-dodoc
   • 对于 npm: npm i @primitivefi/hardhat-dodoc

问题2: 文档生成失败，提示缺少 NatSpec 注释

问题描述: 在编译项目时，文档生成失败，提示某些 Solidity 合约缺少 NatSpec 注释。

解决步骤:

1. 检查合约注释: 确保所有需要生成文档的 Solidity 合约都使用了 NatSpec 格式进行注释。例如：

   /// @notice 当函数被调用时执行另一个操作
   /// @dev 关于函数调用时执行另一个操作的更多信息
   /// @param num 一个随机数
   /// @return 一个随机变量
   function anotherThing(uint256 num) external pure returns (uint256) {
       // 函数实现
   }
   

2. 重新编译: 添加或修正注释后，重新编译项目：
   • 对于 yarn: yarn hardhat compile
   • 对于 npm: npx hardhat compile

问题3: 生成的文档未出现在指定目录

问题描述: 文档生成成功，但生成的文档未出现在项目根目录的 docs 文件夹中。

解决步骤:

1. 检查配置文件: 确保在 hardhat.config.js 或 hardhat.config.ts 文件中正确引入了 @primitivefi/hardhat-dodoc 插件。例如：

   // 使用 JavaScript
   require('@primitivefi/hardhat-dodoc');
   
   // 使用 ES6 或 TypeScript
   import '@primitivefi/hardhat-dodoc';
   

2. 手动触发文档生成: 如果文档仍未生成，可以手动触发文档生成任务：
   • 对于 yarn: yarn hardhat dodoc
   • 对于 npm: npx hardhat dodoc
3. 检查输出目录: 确保项目根目录下存在 docs 文件夹，并且该文件夹具有写权限。

通过以上步骤，新手可以顺利解决在使用 primitive-dodoc 项目时遇到的常见问题。

primitive-dodoc ☄️ Zero-config Hardhat plugin to generate documentation for all your Solidity contracts. 项目地址: https://gitcode.com/gh_mirrors/pr/primitive-dodoc