Все слышали выражение: "Хороший код не нуждается в комментариях". Это неоспоримая истина и ложь одновременно.
Согласно официальной документации в Solidity можно использовать специальную форму написания комментариев. Эта специальная форма называется Ethereum Natural Language Specification Format (NatSpec).
Основным ориентиром при создание NatSpec был Doxygen.
Важно! Рекомендуется, чтобы контракты Solidity были полностью аннотированы с использованием NatSpec для всех общедоступных интерфейсов (все что будет определено в ABI)
На основе комментариев можно сгенерировать документацию для смарт-контрактов при помощи:
- Компилятор Solidity.
- Решение от OpenZeppelin по генерации документации.