NatSpec Formatı
Solidity sözleşmeleri, fonksiyonlar, dönüş değişkenleri ve daha fazlası için zengin dokümantasyon sağlamak üzere özel bir yorum biçimi kullanabilir. Bu özel form Ethereum Doğal Dil Belirtim Formatı( Ethereum Natural Language Specification Format) (NatSpec) olarak adlandırılır.
Not
NatSpec, Doxygen’den esinlenmiştir. Doxygen tarzı yorumlar ve etiketler kullansa da, Doxygen ile olan sıkı uyumluluğunu sürdürme niyeti yoktur. Lütfen aşağıda listelenen desteklenmiş etiketleri dikkatlice inceleyin.
Bu dokümantasyon, geliştirici odaklı mesajlar ve son kullanıcıya yönelik mesajlar olarak bölümlere ayrılmıştır. Bu mesajlar son kullanıcıya (insan) sözleşme ile etkileşime gireceği (örneğin bir işlem imzalayacağı) zaman gösterilebilir.
Solidity sözleşmelerinin tüm genel arayüzler (ABI’deki her şey) için NatSpec kullanılarak tamamen açıklanması önerilir.
NatSpec, akıllı sözleşme yazarının kullanacağı ve Solidity derleyicisi tarafından anlaşılan yorumlar için biçimlendirme içerir. Ayrıca bu yorumları makine tarafından okunabilir bir biçime dönüştüren Solidity derleyicisinin çıktısı da aşağıda detaylı olarak açıklanmıştır.
NatSpec, üçüncü taraf araçlar tarafından kullanılan ek açıklamaları da içerebilir. Bunlar
büyük olasılıkla @custom:<name> etiketi aracılığıyla gerçekleştirilir ve iyi bir kullanım
örneği analiz ve doğrulama araçlarıdır.
Dokümantasyon Örneği
Dokümantasyon, Doxygen notasyon formatı kullanılarak her contract , interface ,
library , function ve event üzerine eklenir. Bir public durum değişkeni,
NatSpec’in kullanım amaçları doğrultusunda bir fonksiyon a eşdeğerdir.
Solidity için tek veya çok satırlı yorumlar için
//veya/**ve*/ile sonlandırmayı tercih edebilirsiniz.Vyper için, iç içeriğe yalın yorumlarla girintili
"""kullanın. Vyper belgelerine <https://vyper.readthedocs.io/en/latest/natspec.html>`__ bakınız.
Aşağıdaki örnekte, mevcut tüm etiketler kullanılarak bir sözleşme ve bir fonksiyon gösterilmektedir.
Not
Solidity derleyicisi, etiketleri yalnızca external veya public olmaları durumunda yorumlamaktadır. Internal ve private fonksiyonlarınız için benzer yorumlar kullanabilirsiniz, ancak bunlar çözümlenmeyecektir.
Bu özellik belki gelecekte değişebilir.
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.2 < 0.9.0;
/// @title Ağaçlar için bir simülatör
/// @author Larry A. Gardner
/// @notice Bu sözleşmeyi yalnızca en sade simulasyonlar için kullanabilirsiniz
/// @dev Tüm fonksiyon çağrıları şu anda yan etkiler olmadan uygulanmaktadır
/// @custom:experimental Bu deneysel bir sözleşmedir.
contract Tree {
/// @notice Canlı ağaçlar için ağaç yaşını yıl olarak hesaplayın, üst sayıya yuvarlayın
/// @dev Alexandr N. Tetearing algoritması doğruluğu artırabilir
/// @param rings Dendrokronolojik örnekten elde edilen halka sayısı
/// @return Yıl cinsinden yaş, kısmi yıllar için yuvarlanır
function age(uint256 rings) external virtual pure returns (uint256) {
return rings + 1;
}
/// @notice Ağacın sahip olduğu yaprak miktarını döndürür.
/// @dev Yalnızca sabit bir sayı döndürür.
function leaves() external virtual pure returns(uint256) {
return 2;
}
}
contract Plant {
function leaves() external virtual pure returns(uint256) {
return 3;
}
}
contract KumquatTree is Tree, Plant {
function age(uint256 rings) external override pure returns (uint256) {
return rings + 2;
}
/// Bu spesifik ağaç türünün sahip olduğu yaprak miktarını döndürür
/// @inheritdoc Tree
function leaves() external override(Tree, Plant) pure returns(uint256) {
return 3;
}
}
Dokümantasyon Çıktısı
Derleyici tarafından çözümlendiğinde, yukarıdaki örnekteki gibi belgeler iki farklı JSON dosyası üretecektir. Biri son kullanıcı tarafından bir fonksiyon çalıştırıldığında bildirim olarak tüketilmek üzere, diğeri ise geliştirici tarafından kullanılmak üzere tasarlanmıştır.
Yukarıdaki sözleşme ex1.sol olarak kaydedilirse,
belgeleri kullanarak oluşturabilirsiniz:
solc --userdoc --devdoc ex1.sol
Çıktı aşağıda verilmiştir.
Not
Solidity 0.6.11 sürümünden itibaren NatSpec çıktısı ayrıca bir version ve
bir kind alanı içerir. Şu anda version 1 olarak ayarlanmıştır ve
kind user veya dev alanlarından biri olmalıdır. Gelecekte, eski
sürümleri kullanımdan kaldırarak yeni sürümlerin tanıtılması mümkündür.
Kullanıcı Dokümantasyonu
Yukarıdaki dokümantasyon çıktı olarak aşağıdaki kullanıcı dokümantasyonu JSON dosyasını üretecektir:
{
"version" : 1,
"kind" : "user",
"methods" :
{
"age(uint256)" :
{
"notice" : "Calculate tree age in years, rounded up, for live trees"
}
},
"notice" : "You can use this contract for only the most basic simulation"
}
Metodları bulmak için anahtarın sadece fonksiyonun adı değil, Contract ABI da tanımlandığı gibi fonksiyonun kanonik imzası olduğunu unutmayın.
Geliştirici Dokümantasyonu
Kullanıcı dokümantasyon dosyasının yanı sıra, bir geliştirici dokümantasyon JSON dosyası da üretilmeli ve aşağıdaki gibi görünmelidir:
{
"version" : 1,
"kind" : "dev",
"author" : "Larry A. Gardner",
"details" : "All function calls are currently implemented without side effects",
"custom:experimental" : "This is an experimental contract.",
"methods" :
{
"age(uint256)" :
{
"details" : "The Alexandr N. Tetearing algorithm could increase precision",
"params" :
{
"rings" : "The number of rings from dendrochronological sample"
},
"return" : "age in years, rounded up for partial years"
}
},
"title" : "A simulator for trees"
}