JuliaDocs/Documenter.jl

Better "no docs found" error message

Open

#2334 aperta il 6 nov 2023

Vedi su GitHub
 (3 commenti) (1 reazione) (0 assegnatari)Julia (513 fork)batch import
Type: Enhancementhelp wanted

Metriche repository

Star
 (910 star)
Metriche merge PR
 (Merge medio 16g 9h) (3 PR mergiate in 30 g)

Descrizione

Whenever I get the error message that reads

Error: no doc found for reference '[`rms`](@ref)' in src/validation.md.

I can never remember if the problem is

  1. There is no docstring in the source code for this reference.
  2. There is no docstring included in the docs for this reference.
  3. Number 2 as a consequence of number 1.
  4. Number 2 as a consequence of rms not being exported.

Would it be possible to somehow be more precise in these error messages? For example, I was just debugging why I got the message above, and it turned out that

  1. I did have rms in a @docs block.
  2. rms did have a docstring in the source
  3. rms was not exported.

It took me quite a while to figure out that the problem was number 3 here, and it's not the first time :sweat_smile:

Guida contributor

Direzione di ricerca
Indaga dove viene generato l'errore 'no doc found for reference' in Documenter.jl. Identifica il percorso del codice che controlla i docstring e le esportazioni. Proponi un messaggio di errore più specifico che distingua tra docstring mancante, blocco @docs mancante ed esportazione mancante.
Tech stack
julia
Dominio
documentation
Tipo issue
Funzionalità
DifficoltàQuanto dovrebbe essere impegnativa per un nuovo contributor.
2
Tempo stimatoTempo stimato per completare e verificare uno scope piccolo.
1-3 ore
Stato attivitàQuanto è probabile che la issue sia ancora attiva e reviewable.
Attiva
ChiarezzaQuanto chiaramente la issue descrive problema, scope e risultato atteso.
Chiara
Prerequisiti
JuliaGit
Adatta ai principiantiQuanto la issue è adatta a contributor alla prima esperienza.
75