فرمت NatSpec:
قراردادهای Solidity میتوانند از یک فرم خاص از کامنتها استفاده کنند تا مستندات کاملی را برای توابع، متغیرهای بازگشتی و سایر موارد فراهم کنند. این فرم خاص با نام Natural Language Specification (NatSpec) اتریوم شناخته میشود.
NatSpec شامل قالببندی برای کامنتهایی است که نویسنده قرارداد هوشمند استفاده میکند و توسط کامپایلر Solidity قابل درک است.
جدول زیر هدف هر تگ NatSpec را توضیح میدهد و نشان میدهد کجا میتوان از آن استفاده کرد. تمام تگها اختیاری هستند. به عنوان یک حالت خاص، اگر شما یک کامنت با سه خط/// یا یک کامنت با ستاره /** بنویسید و هیچ تگ خاصی را به آن اضافه نکنید، کامپایلر Solidity آن را به عنوان یک توضیح معمولی در نظر میگیرد.
برای کسب اطلاعات بیشتر، به منبع https://docs.soliditylang.org/en/v0.8.6/natspec-format.html مراجعه فرمایید.
پی نوشت 1:
به عبارت دیگر، این تگ برای ارث بری از تمام تگهایی که در تابع پایه (تابعی که در قرارداد پایه تعریف شده است) وجود دارد، استفاده میشود. با اضافه کردن این تگ به تابع فعلی، تمام تگهای گمشده از تابع پایه به تابع فعلی کپی میشوند و در مستندسازی نهایی قرارداد نمایش داده میشوند.
عبارت ” در تابع فعلی گم شدهاند” به این معنی است که توضیحات و تگهایی که در تابع پایه (BaseContract) وجود دارند و در تابع فعلی (MyContract) وجود ندارند، به عنوان تگهای گمشده در نظر گرفته میشوند. به عبارت دیگر، اگر در تابع پایه (BaseContract) توضیحاتی مانند @notice یا @dev وجود داشته باشد و در تابع فعلی (MyContract) این توضیحات حذف شده باشند، با استفاده از تگ @inheritdoc(BaseContract) میتوانید تمام تگهای گمشده را از تابع پایه به تابع فعلی کپی کنید. این کار باعث میشود توضیحات و تگهای مربوط به تابع پایه در مستندسازی نهایی قرارداد فعلی نمایش داده شوند.
پی نوشت 2:
استفاده از تگ @custom:experimental به توسعهدهندگان و کاربران نهایی اطلاع میدهد که قرارداد در حال توسعه است و ممکن است دارای خطاها یا محدودیتهایی باشد. این تگ به عنوان یک هشدار استفاده میشود تا کاربران از استفاده از قرارداد آزمایشی بدون درک کامل از عملکرد و ریسکهای آن خودداری کنند.
نحوه کامنت گذاری با استفاده از افزونه VS Code Solidity Comments :
برای اضافه کردن توضیحات به کد Solidity در ویژوال استودیو کد، مراحل زیر را دنبال کنید:
- افزونه VS Code Solidity Comments را از بخش Extensions نصب کنید.
- روی خط کد مورد نظر قرار بگیرید و کلیدهای Ctrl+Shift+P را فشار دهید.
- از منوی باز شده، گزینه Add Solidity Comments را انتخاب کنید.
افزونه VS Code Solidity Comments برای کلمات کلیدی contract ، interfaceو library، چهار کامنت به شرح زیر اضافه می کند:
- @author: نام نویسنده کد
- @title: عنوان کد
- @dev: توضیحات فنی کد
- @notice: نکات مهم در مورد کد
افزونه VS Code Solidity Comments برای کلمات کلیدی function و modifier، چهار کامنت به شرح زیر اضافه می کند:
- @notice: نکات مهم در مورد تابع یا اصلاح کننده
- @dev: توضیحات فنی تابع یا اصلاح کننده
- @param: توضیحات مربوط به پارامترهای تابع یا اصلاح کننده
- @return: نوع مقدار بازگشتی تابع یا اصلاح کننده
نکته 1:
فایل کد Solidity باید با پسوند sol ذخیره شود.
نکته 2:
افزونه VS Code Solidity Comments فقط برچسب های @title، @author، @notice، @dev، @param و @return را پشتیبانی می کند. سایر برچسب های NatSpec باید به صورت دستی نوشته شوند.
نحوه مستندسازی با استفاده از پلاگین DOCGEN – DOCUMENTATION GENERATOR :
میتوانید کد Solidity را در ریمیکس براساس فرمت Natspec، به روش دستی کامنتگذاری کنید یا با استفاده از ویژوال استودیو کد انجام دهید.
- برای ایجاد داکیومنتها، روی فایل قرارداد کلیک راست کنید و گزینه “Generate Docs” را انتخاب کنید. این عمل باعث فعال شدن پلاگین DOCGEN – DOCUMENTATION GENERATOR از بخش PLUGIN MANAGER میشود. سپس کمی صبر کنید تا داکیومنتها ساخته شوند.
- بعد از گذشت یک مدت زمان، پنجره Docgen Viewer ظاهر میشود که داکیومنت ساخته شده را نمایش میدهد. برای دفعات بعدی که این فایل Solidity را باز میکنید، این پنجره به طور خودکار باز میشود.
نکته 3:
وقتی شما “Generate Docs” را انتخاب میکنید، یک پوشه با نام “docs” ساخته میشود که شامل یک فایل با نام قرارداد و پسوند “md” است. این فایل حاوی داکیومنت قرارداد با سینتکس Markdown میباشد.
نکته 4:
اگر روی فایل قرارداد کلیک راست کنید و گزینه “Generate UML” را انتخاب کنید، میتوانید ساختار UML قرارداد را مشاهده کنید.
