DocstringParsingError: Documentation tag @author not valid for functions.
Ai pus în NatSpec un tag care nu e permis în acel loc: @author și @title merg doar deasupra contractului, iar @param și @return doar la funcții, evenimente și erori. Mută tag-ul la declarația potrivită sau șterge-l.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
NatSpec are reguli despre ce tag merge unde. Pe scurt:
@titleși@author: la contracte, interfețe și biblioteci;@notice,@dev: aproape oriunde (contracte, funcții, variabile publice, evenimente, erori);@param: la funcții, modifiers, evenimente, erori;@return: la funcții și variabile publice;@inheritdoc: la funcțiile care suprascriu o funcție documentată.
Când un comentariu /// sau /** */ conține un tag nepermis pentru declarația de sub el, compilatorul oprește compilarea cu Documentation tag @x not valid for .... Ultimul cuvânt îți spune ce tip de declarație a găsit: functions, contracts, events, non-public state variables.
Cel mai des se întâmplă când pui antetul contractului (@title, @author) deasupra primei funcții, sau @param deasupra lui contract.
De ce apare: cauzele frecvente
1Antetul contractului pus pe o funcție
contract Biblioteca {
/// @author Ana Popescu
function adauga() external { }
}/// @author Ana Popescu
contract Biblioteca {
function adauga() external { }
}@author descrie contractul, deci stă deasupra lui contract.
2@param deasupra contractului
/// @param pret pretul initial
contract Magazin {
constructor(uint256 pret) { }
}contract Magazin {
/// @param pret pretul initial
constructor(uint256 pret) { }
}Parametrii sunt ai constructorului, deci documentația lor stă deasupra constructorului.
Repară eroarea, direct în pagină
Contractul Biblioteca are documentația scrisă în locul greșit: compilarea dă DocstringParsingError: Documentation tag @author not valid for functions. Mută rândurile @title și @author deasupra lui contract Biblioteca, iar deasupra funcției lasă doar @notice. Scriptul adaugă două cărți și afișează numărul lor.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract Biblioteca {
uint256 public carti;
/// @title Biblioteca scolii
/// @author Ana Popescu
/// @notice Adauga o carte
function adauga() external {
carti += 1;
}
}Cărți: 2
Indiciu
@author și @title descriu contractul, nu funcția.
Reparația
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
/// @title Biblioteca scolii
/// @author Ana Popescu
contract Biblioteca {
uint256 public carti;
/// @notice Adauga o carte
function adauga() external {
carti += 1;
}
}De ce merge
Compilatorul verifică fiecare tag NatSpec față de declarația de sub el. @title și @author sunt permise doar la contracte, interfețe și biblioteci, iar sub ele era o funcție. Mutate deasupra lui contract Biblioteca, descriu ce trebuie, iar funcția păstrează doar @notice, care e valid. Codul compilează și scriptul numără 2 cărți.
Alte forme ale mesajului
DocstringParsingError: Documentation tag @param not valid for contracts.DocstringParsingError: Documentation tag @title not valid for functions.
Cum o eviți pe viitor
- Pune
@title,@authorși@noticegeneral deasupra cuvântuluicontract. - Pune
@notice,@param,@returndeasupra fiecărei funcții. - Pentru detalii tehnice oriunde, folosește
@dev. - Pentru note care nu sunt documentație, folosește comentarii simple
//, pe care compilatorul nu le verifică. - Dacă nu ești sigur unde merge un tag, compilează după fiecare bloc de documentație: eroarea indică exact linia comentariului.
Întrebări frecvente
Comentariile // sunt verificate?
Nu. Doar /// și /** ... */ sunt NatSpec. Un // @author e un comentariu obișnuit și nu dă eroare.
Pot folosi tag-uri proprii?
Da, cu prefixul @custom:, de exemplu /// @custom:security-contact securitate@exemplu.ro. Tag-urile necunoscute fără acest prefix dau tot DocstringParsingError.
Erori înrudite
DocstringParsingError: Documented parameter "suma" not found in the parameter list of the function. Comentariul NatSpec (/// @param suma) descrie un parametru care nu există în funcție: parametrul a fost redenumit sau șters, iar documentația a rămas veche. Fă numele din @param identic cu cel din semnătura funcției. Warning: SPDX license identifier not provided in source file. Before publishing, consider adding a comment containing "SPDX-License-Identifier: <SPDX-License>" to each source file. Use "SPDX-License-Identifier: UNLICENSED" for non-open-source code. Please see https://spdx.org for more information. Este un avertisment, nu o eroare: fișierului îi lipsește comentariul cu licența. Adaugă pe prima linie // SPDX-License-Identifier: MIT (sau UNLICENSED pentru cod închis), iar avertismentul dispare. ParserError: Expected pragma, import directive or contract/interface/library/struct/enum/constant/function/error definition. În afara unui contract ai scris ceva ce nu are voie acolo, de cele mai multe ori pentru că ai o acoladă } în plus care a închis contractul prea devreme. Numără acoladele și mută codul înapoi în contract. Învață Solidity de la zero, cu exerciții la fiecare lecție
Curs Solidity și Smart Contracts: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
