...
Eroare Solidity · Erori de sintaxă, pragma și licență

DocstringParsingError: Documentation tag @author not valid for functions.

Pe scurt

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

Greșit
SOLIDITY
contract Biblioteca {
    /// @author Ana Popescu
    function adauga() external { }
}
Corect
SOLIDITY
/// @author Ana Popescu
contract Biblioteca {
    function adauga() external { }
}

@author descrie contractul, deci stă deasupra lui contract.

2@param deasupra contractului

Greșit
SOLIDITY
/// @param pret pretul initial
contract Magazin {
    constructor(uint256 pret) { }
}
Corect
SOLIDITY
contract Magazin {
    /// @param pret pretul initial
    constructor(uint256 pret) { }
}

Parametrii sunt ai constructorului, deci documentația lor stă deasupra constructorului.

Repară tu

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.

Codul care dă eroarea
SOLIDITY
// 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;
    }
}
După reparație, programul afișează
Cărți: 2
Indiciu

@author și @title descriu contractul, nu funcția.

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 @notice general deasupra cuvântului contract.
  • Pune @notice, @param, @return deasupra 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

← Toate erorile Solidity

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.