JuliaDocs/Documenter.jl

Better "no docs found" error message

Aberta

#2.334 aberto em 6 de nov. de 2023

Ver no GitHub
 (3 comentários) (1 reação) (0 responsável)Julia (513 forks)batch import
Type: Enhancementhelp wanted

Métricas do repositório

Stars
 (910 estrelas)
Métricas de merge de PR
 (Mesclagem média 16d 9h) (3 fundiu PRs em 30d)

Description

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:

Guia do colaborador

Direção de pesquisa
Investigue onde o erro 'no doc found for reference' é gerado no Documenter.jl. Identifique o caminho do código que verifica docstrings e exportações. Proponha uma mensagem de erro mais específica que diferencie entre docstring ausente, bloco @docs ausente e exportação ausente.
Pilha de tecnologia
julia
Domain
documentation
Tipo Issue
Funcionalidade
DifficultyDificuldade de implementação estimada para um novo contribuidor, de 1 para alterações muito pequenas a 5 para trabalho de nível especializado.
2
Tempo estimadoUm intervalo de tempo aproximado para um colaborador experiente investigar, implementar, testar e preparar um pull request.
1-3 horas
Status da atividadeQuão disponível o issue aparece agora: novo, ativo, obsoleto, bloqueado ou aguardando entrada do mantenedor.
Ativo
ClarityCom que clareza o issue explica a mudança esperada, os critérios de aceitação e a próxima etapa.
Claro
Prerequisites
JuliaGit
Simpatia para novatosUma pontuação de 1 a 100 que estima o quão acessível este issue é para colaboradores iniciantes.
75