JuliaDocs/Documenter.jl

Better "no docs found" error message

Open

#2,334 opened on Nov 6, 2023

View on GitHub
 (3 comments) (1 reaction) (0 assignees)Julia (910 stars) (513 forks)batch import
Type: Enhancementhelp wanted

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:

Contributor guide

Tech stack
None
Domain
documentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Julia programmingDocumenter.jl internals
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
The error message is likely generated in the build or processing pipeline for documentation references. Search for the string 'no doc found for reference' in the repository to locate the source. Examine how references are resolved and whether the cause (missing docstring, not exported, etc.) can be determined. Consider adding specific error messages for each case.