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.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Comentariile care încep cu /// sau /** */ sunt NatSpec: documentația oficială a contractului, pe care compilatorul o citește și o verifică. Pentru fiecare @param nume, compilatorul caută un parametru cu exact acel nume în funcția de dedesubt. Dacă nu îl găsește, compilarea se oprește cu DocstringParsingError, chiar dacă restul codului e corect.
Aproape mereu e o redenumire făcută doar pe jumătate: ai schimbat suma în valoare în semnătură, dar nu și în comentariu. Sau ai copiat comentariul de la altă funcție.
O eroare înrudită apare la valorile întoarse: Documentation tag "@return total" exceeds the number of return parameters. înseamnă că ai mai multe @return decât valori în returns (...), sau că funcția nu întoarce nimic. Linia din mesaj arată comentariul, nu funcția.
De ce apare: cauzele frecvente
1Parametru redenumit, comentariu vechi
/// @param suma valoarea de dublat
function dublu(uint256 valoare) external pure returns (uint256) {
return valoare * 2;
}/// @param valoare valoarea de dublat
function dublu(uint256 valoare) external pure returns (uint256) {
return valoare * 2;
}Numele din @param trebuie să fie exact numele parametrului.
2@return la o funcție care nu întoarce nimic
/// @return total noul total
function adauga(uint256 x) external {
total += x;
}/// @notice Adauga x la total
function adauga(uint256 x) external {
total += x;
}@return e verificat față de lista returns (...); fără valori întoarse, tag-ul nu are ce descrie.
Repară eroarea, direct în pagină
Contractul Calculator are o funcție documentată cu NatSpec, dar compilarea dă DocstringParsingError: Documented parameter "suma" not found in the parameter list of the function. Documentația e cea corectă: redenumește parametrul funcției în suma (și în corpul ei). Scriptul afișează dublul lui 21.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract Calculator {
/// @notice Dubleaza o suma
/// @param suma valoarea de dublat
/// @return dublul sumei
function dublu(uint256 valoare) external pure returns (uint256) {
return valoare * 2;
}
}Dublu: 42
Indiciu
Numele din @param trebuie să apară exact în semnătura funcției.
Reparația
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract Calculator {
/// @notice Dubleaza o suma
/// @param suma valoarea de dublat
/// @return dublul sumei
function dublu(uint256 suma) external pure returns (uint256) {
return suma * 2;
}
}De ce merge
Compilatorul verifică fiecare @param din NatSpec: caută în semnătură un parametru cu același nume. Comentariul vorbea despre suma, iar funcția avea valoare, deci documentația descria ceva inexistent. După redenumire, comentariul și semnătura se potrivesc, contractul compilează, iar dublu(21) întoarce 42.
Alte forme ale mesajului
DocstringParsingError: Documented parameter "y" not found in the parameter list of the function.DocstringParsingError: Documentation tag "@return total" exceeds the number of return parameters.
Cum o eviți pe viitor
- Când redenumești un parametru, folosește redenumirea din editor (Rename Symbol), nu căutare și înlocuire parțială.
- Scrie NatSpec după ce semnătura funcției s-a stabilizat.
- Recitește comentariul când copiezi o funcție ca șablon pentru alta.
- Ține un
@parampentru fiecare parametru și un@returnpentru fiecare valoare întoarsă.
Întrebări frecvente
De ce oprește compilarea un comentariu?
Comentariile /// nu sunt simple comentarii: din ele se generează documentația pentru utilizatori și dezvoltatori (devdoc, userdoc), pe care o afișează portofelele și exploratoarele de blocuri. Compilatorul vrea ca ea să fie corectă. Comentariile // obișnuite nu sunt verificate.
Pot scăpa de eroare schimbând /// în //?
Da, dar pierzi documentația. Reparația bună e să potrivești numele.
Erori înrudite
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. DeclarationError: Undeclared identifier. Folosești un nume (variabilă, funcție, eveniment) pe care compilatorul nu îl găsește: e scris diferit față de declarație, nu a fost declarat sau nu e vizibil în acel loc. Verifică literele mari și mici și declarația. Warning: Unused local variable. Ai declarat o variabilă locală pe care nu o folosești nicăieri. Fie e un rest de cod care trebuie șters, fie (mai des) ai calculat ceva și ai uitat să folosești rezultatul. Folosește variabila sau șterge-o. Î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.
