blob: 9709597308ca1e2d6251717a55f75d1de5064f21 [file]
/-
Copyright (c) 2025 Lean FRO, LLC. All rights reserved.
Released under Apache 2.0 license as described in the file LICENSE.
Authors: David Thrane Christiansen
-/
module
prelude
import Lean.Environment
import Lean.Exception
import Lean.Log
import Lean.Elab.DocString
import Lean.DocString.Extension
import Lean.DocString.Links
import Lean.Parser.Types
import Lean.DocString.Parser
import Lean.ResolveName
public import Lean.Elab.Term.TermElabM
import Std.Data.HashMap
public section
set_option linter.missingDocs true
namespace Lean
open Lean.Elab.Term (TermElabM)
/--
Validates all links to the Lean reference manual in `docstring`.
This is intended to be used before saving a docstring that is later subject to rewriting with
`rewriteManualLinks`.
-/
def validateDocComment
[Monad m] [MonadLiftT IO m] [MonadLog m] [AddMessageContext m] [MonadOptions m]
(docstring : TSyntax `Lean.Parser.Command.docComment) :
m Unit := do
let str := docstring.getDocString
let pos? := docstring.raw[1].getHeadInfo? >>= (·.getPos?)
let (errs, out) ← (rewriteManualLinksCore str : IO _)
for (⟨start, stop⟩, err) in errs do
-- Report errors at their actual location if possible
if let some pos := pos? then
let urlStx : Syntax := .atom (.synthetic (pos + start) (pos + stop)) (str.extract start stop)
logErrorAt urlStx err
else
logError err
open Lean.Doc in
open Parser in
/--
Adds a Verso docstring to the specified declaration, which should already be present in the
environment.
`binders` should be the syntax of the parameters to the constant that is being documented, as a null
node that contains a sequence of bracketed binders. It is used to allow interactive features such as
document highlights and “find references” to work for documented parameters. If no parameter binders
are available, pass `Syntax.missing` or an empty null node.
-/
def versoDocString
(declName : Name) (binders : Syntax) (docComment : TSyntax `Lean.Parser.Command.docComment) :
TermElabM (Array (Doc.Block ElabInline ElabBlock) × Array (Doc.Part ElabInline ElabBlock Empty)) := do
let text ← getFileMap
-- TODO fallback to string version without nice interactivity
let some startPos := docComment.raw[1].getPos? (canonicalOnly := true)
| throwErrorAt docComment m!"Documentation comment has no source location, cannot parse"
let some endPos := docComment.raw[1].getTailPos? (canonicalOnly := true)
| throwErrorAt docComment m!"Documentation comment has no source location, cannot parse"
-- Skip trailing `-/`
let endPos := text.source.prev <| text.source.prev endPos
let endPos := if endPos ≤ text.source.endPos then endPos else text.source.endPos
have endPos_valid : endPos ≤ text.source.endPos := by
unfold endPos
split <;> simp [*]
let env ← getEnv
let ictx : InputContext :=
.mk text.source (← getFileName) (fileMap := text)
(endPos := endPos) (endPos_valid := endPos_valid)
let pmctx : ParserModuleContext := {
env,
options := ← getOptions,
currNamespace := (← getCurrNamespace),
openDecls := (← getOpenDecls)
}
let s := mkParserState text.source |>.setPos startPos
-- TODO parse one block at a time for error recovery purposes
let s := (Doc.Parser.document).run ictx pmctx (getTokenTable env) s
if !s.allErrors.isEmpty then
for (pos, _, err) in s.allErrors do
logMessage {
fileName := (← getFileName),
pos := text.toPosition pos,
-- TODO end position
data := err.toString
}
return (#[], #[])
else
let stx := s.stxStack.back
let stx := stx.getArgs
Doc.elabBlocks (stx.map (⟨·⟩)) |>.exec declName binders
open Lean.Doc in
open Parser in
/--
Adds a Verso docstring to the specified declaration, which should already be present in the
environment. The docstring is added from a string value, rather than syntax, which means that the
interactive features are disabled.
-/
def versoDocStringFromString
(declName : Name) (docComment : String) :
TermElabM (Array (Doc.Block ElabInline ElabBlock) × Array (Doc.Part ElabInline ElabBlock Empty)) := do
let env ← getEnv
let ictx : InputContext := .mk docComment (← getFileName)
let text := ictx.fileMap
let pmctx : ParserModuleContext := {
env,
options := ← getOptions,
currNamespace := (← getCurrNamespace),
openDecls := (← getOpenDecls)
}
let s := mkParserState docComment
-- TODO parse one block at a time for error recovery purposes
let s := (Doc.Parser.document).run ictx pmctx (getTokenTable env) s
if !s.allErrors.isEmpty then
for (pos, _, err) in s.allErrors do
logError err.toString
return (#[], #[])
else
let stx := s.stxStack.back
let stx := stx.getArgs
let msgs ← Core.getAndEmptyMessageLog
let (val, msgs') ←
try
let range? := (← getRef).getRange?
let val ←
Elab.withEnableInfoTree false <| withTheReader Core.Context ({· with fileMap := text}) <|
(Doc.elabBlocks (stx.map (⟨·⟩))).exec declName (mkNullNode #[]) (suggestionMode := .batch)
let msgs' ← Core.getAndEmptyMessageLog
pure (val, msgs')
finally
Core.setMessageLog msgs
-- Adjust messages to show them at the call site
for msg in msgs'.toArray do
logAt (← getRef) msg.data (severity := msg.severity)
pure val
/--
Adds a Markdown docstring to the environment, validating documentation links.
-/
def addMarkdownDocString
[Monad m] [MonadLiftT IO m] [MonadOptions m] [MonadEnv m]
[MonadError m] [MonadLog m] [AddMessageContext m]
(declName : Name) (docComment : TSyntax `Lean.Parser.Command.docComment) :
m Unit := do
if declName.isAnonymous then
-- This case might happen on partial elaboration; ignore instead of triggering any panics below
return
unless (← getEnv).getModuleIdxFor? declName |>.isNone do
throwError m!"invalid doc string, declaration `{.ofConstName declName}` is in an imported module"
validateDocComment docComment
let docString : String ← getDocStringText docComment
modifyEnv fun env => docStringExt.insert env declName docString.removeLeadingSpaces
/--
Adds an elaborated Verso docstring to the environment.
-/
def addVersoDocStringCore [Monad m] [MonadEnv m] [MonadLiftT BaseIO m] [MonadError m]
(declName : Name) (docs : VersoDocString) : m Unit := do
let throwImported {α} : m α :=
throwError s!"invalid doc string, declaration '{declName}' is in an imported module"
unless (← getEnv).getModuleIdxFor? declName |>.isNone do
throwImported
modifyEnv fun env =>
versoDocStringExt.insert env declName docs
/--
Adds a Verso docstring to the environment.
`binders` should be the syntax of the parameters to the constant that is being documented, as a null
node that contains a sequence of bracketed binders. It is used to allow interactive features such as
document highlights and “find references” to work for documented parameters. If no parameter binders
are available, pass `Syntax.missing` or an empty null node.
-/
def addVersoDocString
(declName : Name) (binders : Syntax) (docComment : TSyntax `Lean.Parser.Command.docComment) :
TermElabM Unit := do
unless (← getEnv).getModuleIdxFor? declName |>.isNone do
throwError s!"invalid doc string, declaration '{declName}' is in an imported module"
let (blocks, parts) ← versoDocString declName binders docComment
addVersoDocStringCore declName ⟨blocks, parts⟩
/--
Adds a Verso docstring to the environment from a string value, which disables the interactive
features. This should be used for programs that add documentation when there is no syntax available.
-/
def addVersoDocStringFromString (declName : Name) (docComment : String) :
TermElabM Unit := do
unless (← getEnv).getModuleIdxFor? declName |>.isNone do
throwError s!"invalid doc string, declaration '{declName}' is in an imported module"
let (blocks, parts) ← versoDocStringFromString declName docComment
addVersoDocStringCore declName ⟨blocks, parts⟩
/--
Adds a docstring to the environment. If `isVerso` is `false`, then the docstring is interpreted as
Markdown.
-/
def addDocStringOf
(isVerso : Bool) (declName : Name) (binders : Syntax)
(docComment : TSyntax `Lean.Parser.Command.docComment) :
TermElabM Unit := do
if isVerso then
addVersoDocString declName binders docComment
else
addMarkdownDocString declName docComment
/--
Interprets a docstring that has been saved as a Markdown string as Verso, elaborating it. This is
used during bootstrapping.
-/
def makeDocStringVerso (declName : Name) : TermElabM Unit := do
let some doc ← findInternalDocString? (← getEnv) declName (includeBuiltin := true)
| throwError "No documentation found for `{.ofConstName declName}`"
let .inl md := doc
| throwError "Documentation for `{.ofConstName declName}` is already in Verso format"
removeBuiltinDocString declName
removeDocStringCore declName
addVersoDocStringFromString declName md
/--
Adds a docstring to the environment.
If the option `doc.verso` is `true`, the docstring is processed as a Verso docstring. Otherwise, it
is considered a Markdown docstring, and documentation links are validated. To explicitly control
whether the docstring is in Verso format, use `addDocStringOf` instead.
For Verso docstrings, `binders` should be the syntax of the parameters to the constant that is being
documented, as a null node that contains a sequence of bracketed binders. It is used to allow
interactive features such as document highlights and “find references” to work for documented
parameters. If no parameter binders are available, pass `Syntax.missing` or an empty null node.
`binders` is not used for Markdown docstrings.
-/
def addDocString
(declName : Name) (binders : Syntax) (docComment : TSyntax `Lean.Parser.Command.docComment) :
TermElabM Unit := do
addDocStringOf (doc.verso.get (← getOptions)) declName binders docComment
/--
Adds a docstring to the environment, if it is provided. If no docstring is provided, nothing
happens.
If the option `doc.verso` is `true`, the docstring is processed as a Verso docstring. Otherwise, it
is considered a Markdown docstring, and documentation links are validated. To explicitly control
whether the docstring is in Verso format, use `addDocStringOf` instead.
For Verso docstrings, `binders` should be the syntax of the parameters to the constant that is being
documented, as a null node that contains a sequence of bracketed binders. It is used to allow
interactive features such as document highlights and “find references” to work for documented
parameters. If no parameter binders are available, pass `Syntax.missing` or an empty null node.
`binders` is not used for Markdown docstrings.
-/
def addDocString'
(declName : Name) (binders : Syntax) (docString? : Option (TSyntax `Lean.Parser.Command.docComment)) :
TermElabM Unit :=
match docString? with
| some docString => addDocString declName binders docString
| none => return ()