Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

stable doc unique ids , index, lightweight symbol references, indicate where a proc is tested; idx #228

Open
timotheecour opened this issue May 18, 2020 · 0 comments

Comments

@timotheecour
Copy link
Owner

timotheecour commented May 18, 2020

use case

allows stable references for any link (eg runnableExample, symbol, doc paragraph, referencing doc from a compiler error msg etc)
eg: for this nim-lang#14340 (comment)

No stack traceback available
To create a stacktrace, rerun compilation with ./koch temp r <file>, see https://nim-lang.github.io/Nim/intern.html#bootstrapping-the-compiler

note

would replace those links:

  ## * `& proc <#&,seq[T][T],seq[T][T]>`_

which are hard to type/read and get stale if a proc gets updated (eg new optional param)

would also replace anchors-based-on-title which often get stale after title changes

eg

datestring2
D20200517T232720
or use oids
use unique prefix that gets correctly interpreted/highlighted/indexed by docgen + compiler

implementation

expose: setIndexTerm ?
recognize special links eg: foo:here

related

proc takeImplicitAddr(c: PContext, n: PNode; isLent: bool): PNode =
  # See RFC #7373, calls returning 'var T' are assumed to
  # return a view into the first argument (if there is one):
  let root = exprRoot(n)
  if root != nil and root.owner == c.p.owner:
    if root.kind in {skLet, skVar, skTemp} and sfGlobal notin root.flags:
      localError(c.config, n.info, "'$1' escapes its stack frame; context: '$2'; see $3/var_t_return.html" % [
        root.name.s, renderTree(n, {renderNoComments}), explanationsBaseUrl])

indicate where a proc is tested

block: ## `test:isRelativeTo`
  doAssert isRelativeTo("/foo", "/")

ligthweight references

  • nim doc can give a warning when baz is ambiguous (defined in multiple modules), or not defined at all
  • no warning when it's just an overload but defined in a single module (frequent case)
  • hyperlink can resolve to just the 1st found overload, or to entry in the index, or to populating dochack search using clickable selections
proc fun* =
  ## see `mod.bar`, see `baz`

ligthweight definitions

definitions can happen in any doc comment, eg:

runnableExamples: ## `def:importcExample`
	# code showing how to use {.importc.}

example

lent isn't documented in manual and searching for lent in index returns nothing
it turns out it's document here https://nim-lang.github.io/Nim/destructors.html
=> but it should be in index, and it should be searchable by lent

see also: idx feature in docgen

  • This is similar to super:idx: in ordinary OO languages.
    but it doesn't work as well, it only points to here from index but doesn't implement ODR

  • note: idx terms should be highlighted but they're not:

> If b.len is not exactly the number of elements that are referred to by x, a splice is performed:
  • it shouldn't show Misc but smthg more informative
  • should be searchable wo regex, eg shown in index as -case: (note the prefix -)
  • should be searchable in search box
  • doesn't work if inside RST file eg
doc/manual.rst:6144:21:compile a Nim `case`:idx: statement. Syntactically it has to be used as a

links

nim-lang#9477

@timotheecour timotheecour changed the title stable doc unique ids stable doc unique ids , index May 23, 2020
@timotheecour timotheecour changed the title stable doc unique ids , index stable doc unique ids , index, lightweight symbol references, indicate where a proc is tested May 25, 2020
@timotheecour timotheecour changed the title stable doc unique ids , index, lightweight symbol references, indicate where a proc is tested stable doc unique ids , index, lightweight symbol references, indicate where a proc is tested; idx Nov 23, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant