change os.nim doc links to new style (#19102)

compiler/docgen.nim

@@ -954,6 +954,13 @@ proc toLangSymbol(k: TSymKind, n: PNode, baseName: string): LangSymbol =
         if kind != tkSpaces:
           result.generics.add(literal.nimIdentNormalize)
 
+  if k == skType:
+    case n[2].kind
+    of nkEnumTy: result.symTypeKind = "enum"
+    of nkObjectTy: result.symTypeKind = "object"
+    of nkTupleTy: result.symTypeKind = "tuple"
+    else: discard
+
 proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) =
   if (docFlags != kForceExport) and not isVisible(d, nameNode): return
   let

doc/docgen.rst

@@ -399,6 +399,13 @@ recognized fine::
       no backticks: `func [][T](x: openArray[T]): T`_
       escaped:  `func \`[]\`[T](x: openArray[T]): T`_
 
+.. Note:: Types that defined as `enum`, or `object`, or `tuple` can also be
+   referenced with those names directly (instead of `type`)::
+
+     type CopyFlag = enum
+       ...
+     ## Ref. `CopyFlag enum`_
+
 Related Options
 ===============
 

lib/packages/docutils/dochelpers.nim

@@ -17,7 +17,9 @@ import rstast
 
 type
   LangSymbol* = object       ## symbol signature in Nim
-    symKind*: string           ## "proc", "const", etc
+    symKind*: string           ## "proc", "const", "type", etc
+    symTypeKind*: string       ## ""|enum|object|tuple -
+                               ## valid only when `symKind == "type"`
     name*: string              ## plain symbol name without any parameters
     generics*: string          ## generic parameters (without brackets)
     isGroup*: bool             ## is LangSymbol a group with overloads?
@@ -79,7 +81,14 @@ proc toLangSymbol*(linkText: PRstNode): LangSymbol =
   assert linkText.kind in {rnRef, rnInner}
 
   const NimDefs = ["proc", "func", "macro", "method", "iterator",
-                   "template", "converter", "const", "type", "var"]
+                   "template", "converter", "const", "type", "var",
+                   "enum", "object", "tuple"]
+  template resolveSymKind(x: string) =
+    if x in ["enum", "object", "tuple"]:
+      result.symKind = "type"
+      result.symTypeKind = x
+    else:
+      result.symKind = x
   type
     State = enum
       inBeginning
@@ -97,7 +106,7 @@ proc toLangSymbol*(linkText: PRstNode): LangSymbol =
     if curIdent != "":
       case state
       of inBeginning:  doAssert false, "incorrect state inBeginning"
-      of afterSymKind:  result.symKind = curIdent
+      of afterSymKind:  resolveSymKind curIdent
       of beforeSymbolName:  doAssert false, "incorrect state beforeSymbolName"
       of atSymbolName: result.name = curIdent.nimIdentBackticksNormalize
       of afterSymbolName: doAssert false, "incorrect state afterSymbolName"
@@ -195,7 +204,7 @@ proc toLangSymbol*(linkText: PRstNode): LangSymbol =
       let isPostfixSymKind = i > 0 and i == L - 1 and
           result.symKind == "" and s(i) in NimDefs
       if isPostfixSymKind:  # for links like `foo proc`_
-        result.symKind = s(i)
+        resolveSymKind s(i)
       else:
         case state
         of inBeginning:
@@ -235,6 +244,8 @@ proc match*(generated: LangSymbol, docLink: LangSymbol): bool =
       result = docLink.symKind in ["proc", "func"]
     else:
       result = generated.symKind == docLink.symKind
+      if result and docLink.symKind == "type" and docLink.symTypeKind != "":
+        result = generated.symTypeKind == docLink.symTypeKind
     if not result: return
   result = generated.name == docLink.name
   if not result: return

lib/pure/includes/osenv.nim

@@ -56,13 +56,13 @@ when not defined(nimscript):
       ##
       ## If the variable does not exist, `""` is returned. To distinguish
       ## whether a variable exists or it's value is just `""`, call
-      ## `existsEnv(key) proc <#existsEnv,string>`_.
+      ## `existsEnv(key) proc`_.
       ##
       ## See also:
-      ## * `existsEnv proc <#existsEnv,string>`_
+      ## * `existsEnv proc`_
-      ## * `putEnv proc <#putEnv,string,string>`_
+      ## * `putEnv proc`_
-      ## * `delEnv proc <#delEnv,string>`_
+      ## * `delEnv proc`_
-      ## * `envPairs iterator <#envPairs.i>`_
+      ## * `envPairs iterator`_
       runnableExamples:
         assert getEnv("unknownEnv") == ""
         assert getEnv("unknownEnv", "doesn't exist") == "doesn't exist"
@@ -76,10 +76,10 @@ when not defined(nimscript):
       ## Returns true if it exists, false otherwise.
       ##
       ## See also:
-      ## * `getEnv proc <#getEnv,string,string>`_
+      ## * `getEnv proc`_
-      ## * `putEnv proc <#putEnv,string,string>`_
+      ## * `putEnv proc`_
-      ## * `delEnv proc <#delEnv,string>`_
+      ## * `delEnv proc`_
-      ## * `envPairs iterator <#envPairs.i>`_
+      ## * `envPairs iterator`_
       runnableExamples:
         assert not existsEnv("unknownEnv")
 
@@ -90,10 +90,10 @@ when not defined(nimscript):
       ## If an error occurs, `OSError` is raised.
       ##
       ## See also:
-      ## * `getEnv proc <#getEnv,string,string>`_
+      ## * `getEnv proc`_
-      ## * `existsEnv proc <#existsEnv,string>`_
+      ## * `existsEnv proc`_
-      ## * `delEnv proc <#delEnv,string>`_
+      ## * `delEnv proc`_
-      ## * `envPairs iterator <#envPairs.i>`_
+      ## * `envPairs iterator`_
       when defined(windows):
         if key.len == 0 or '=' in key:
           raise newException(OSError, "invalid key, got: " & $(key, val))
@@ -108,10 +108,10 @@ when not defined(nimscript):
       ## If an error occurs, `OSError` is raised.
       ##
       ## See also:ven
-      ## * `getEnv proc <#getEnv,string,string>`_
+      ## * `getEnv proc`_
-      ## * `existsEnv proc <#existsEnv,string>`_
+      ## * `existsEnv proc`_
-      ## * `putEnv proc <#putEnv,string,string>`_
+      ## * `putEnv proc`_
-      ## * `envPairs iterator <#envPairs.i>`_
+      ## * `envPairs iterator`_
       template bail = raiseOSError(osLastError(), key)
       when defined(windows):
         #[ 
@@ -190,10 +190,10 @@ iterator envPairs*(): tuple[key, value: string] {.tags: [ReadEnvEffect].} =
   ## in the second its value.
   ##
   ## Works in native backends, nodejs and vm, like the following APIs:
-  ## * `getEnv proc <#getEnv,string,string>`_
+  ## * `getEnv proc`_
-  ## * `existsEnv proc <#existsEnv,string>`_
+  ## * `existsEnv proc`_
-  ## * `putEnv proc <#putEnv,string,string>`_
+  ## * `putEnv proc`_
-  ## * `delEnv proc <#delEnv,string>`_
+  ## * `delEnv proc`_
   when nimvm:
     for ai in envPairsImplSeq(): yield ai
   else:

lib/pure/includes/oserr.nim

@@ -18,7 +18,7 @@ proc `$`*(err: OSErrorCode): string {.borrow.}
 proc osErrorMsg*(errorCode: OSErrorCode): string =
   ## Converts an OS error code into a human readable string.
   ##
-  ## The error code can be retrieved using the `osLastError proc <#osLastError>`_.
+  ## The error code can be retrieved using the `osLastError proc`_.
   ##
   ## If conversion fails, or `errorCode` is `0` then `""` will be
   ## returned.
@@ -28,8 +28,8 @@ proc osErrorMsg*(errorCode: OSErrorCode): string =
   ## message.
   ##
   ## See also:
-  ## * `raiseOSError proc <#raiseOSError,OSErrorCode,string>`_
+  ## * `raiseOSError proc`_
-  ## * `osLastError proc <#osLastError>`_
+  ## * `osLastError proc`_
   runnableExamples:
     when defined(linux):
       assert osErrorMsg(OSErrorCode(0)) == ""
@@ -63,18 +63,17 @@ proc newOSError*(
   ## Creates a new `OSError exception <system.html#OSError>`_.
   ##
   ## The `errorCode` will determine the
-  ## message, `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_ will be used
+  ## message, `osErrorMsg proc`_ will be used
   ## to get this message.
   ##
-  ## The error code can be retrieved using the `osLastError proc
+  ## The error code can be retrieved using the `osLastError proc`_.
-  ## <#osLastError>`_.
   ##
   ## If the error code is `0` or an error message could not be retrieved,
   ## the message `unknown OS error` will be used.
   ##
   ## See also:
-  ## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_
+  ## * `osErrorMsg proc`_
-  ## * `osLastError proc <#osLastError>`_
+  ## * `osLastError proc`_
   var e: owned(ref OSError); new(e)
   e.errorCode = errorCode.int32
   e.msg = osErrorMsg(errorCode)
@@ -90,7 +89,7 @@ proc newOSError*(
 proc raiseOSError*(errorCode: OSErrorCode, additionalInfo = "") {.noinline.} =
   ## Raises an `OSError exception <system.html#OSError>`_.
   ##
-  ## Read the description of the `newOSError proc <#newOSError,OSErrorCode,string>`_ to learn
+  ## Read the description of the `newOSError proc`_ to learn
   ## how the exception object is created.
   raise newOSError(errorCode, additionalInfo)
 
@@ -109,8 +108,8 @@ proc osLastError*(): OSErrorCode {.sideEffect.} =
   ##   immediately after an OS call fails. On POSIX systems this is not a problem.
   ##
   ## See also:
-  ## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_
+  ## * `osErrorMsg proc`_
-  ## * `raiseOSError proc <#raiseOSError,OSErrorCode,string>`_
+  ## * `raiseOSError proc`_
   when defined(nimscript):
     discard
   elif defined(windows):

lib/pure/includes/osseps.nim

@@ -37,9 +37,9 @@ const
     when doslikeFileSystem: '/'
     else: DirSep
     ## An alternative character used by the operating system to separate
-    ## pathname components, or the same as `DirSep <#DirSep>`_ if only one separator
+    ## pathname components, or the same as DirSep_ if only one separator
     ## character exists. This is set to `'/'` on Windows systems
-    ## where `DirSep <#DirSep>`_ is a backslash (`'\\'`).
+    ## where DirSep_ is a backslash (`'\\'`).
 
   PathSep* =
     when defined(macos) or defined(RISCOS): ','
@@ -55,7 +55,7 @@ const
          defined(PalmOS) or defined(MorphOS): false
     else: true
     ## True if the file system is case sensitive, false otherwise. Used by
-    ## `cmpPaths proc <#cmpPaths,string,string>`_ to compare filenames properly.
+    ## `cmpPaths proc`_ to compare filenames properly.
 
   ExeExt* =
     when doslikeFileSystem: "exe"

tests/stdlib/tdochelpers.nim

@@ -153,3 +153,9 @@ suite "Integration with Nim":
                               outType: "T")
     check(input1.toLangSymbol == expected)
     check(input2.toLangSymbol == expected)
+
+  test "type of type":
+    check ("`CopyFlag enum`_".rstParseTest.toLangSymbol ==
+           LangSymbol(symKind: "type",
+                      symTypeKind: "enum",
+                      name: "Copyflag"))