Missing docs for alloc, alloc0, allocShared ...

[mratsim]

The alloc, alloc0, allocShared, ... procs that are defined here for 0.19 are missing from the documentation:

Nim/lib/system.nim

Lines 1739 to 1851 in f6c5c63

	when not defined(nimscript):
	when hasAlloc:
	proc alloc*(size: Natural): pointer {.noconv, rtl, tags: [], benign.}
	## allocates a new memory block with at least ``size`` bytes. The
	## block has to be freed with ``realloc(block, 0)`` or
	## ``dealloc(block)``. The block is not initialized, so reading
	## from it before writing to it is undefined behaviour!
	## The allocated memory belongs to its allocating thread!
	## Use `allocShared` to allocate from a shared heap.
	proc createU*(T: typedesc, size = 1.Positive): ptr T {.inline, benign.} =
	## allocates a new memory block with at least ``T.sizeof * size``
	## bytes. The block has to be freed with ``resize(block, 0)`` or
	## ``dealloc(block)``. The block is not initialized, so reading
	## from it before writing to it is undefined behaviour!
	## The allocated memory belongs to its allocating thread!
	## Use `createSharedU` to allocate from a shared heap.
	cast[ptr T](alloc(T.sizeof * size))
	proc alloc0*(size: Natural): pointer {.noconv, rtl, tags: [], benign.}
	## allocates a new memory block with at least ``size`` bytes. The
	## block has to be freed with ``realloc(block, 0)`` or
	## ``dealloc(block)``. The block is initialized with all bytes
	## containing zero, so it is somewhat safer than ``alloc``.
	## The allocated memory belongs to its allocating thread!
	## Use `allocShared0` to allocate from a shared heap.
	proc create*(T: typedesc, size = 1.Positive): ptr T {.inline, benign.} =
	## allocates a new memory block with at least ``T.sizeof * size``
	## bytes. The block has to be freed with ``resize(block, 0)`` or
	## ``dealloc(block)``. The block is initialized with all bytes
	## containing zero, so it is somewhat safer than ``createU``.
	## The allocated memory belongs to its allocating thread!
	## Use `createShared` to allocate from a shared heap.
	cast[ptr T](alloc0(sizeof(T) * size))
	proc realloc*(p: pointer, newSize: Natural): pointer {.noconv, rtl, tags: [],
	benign.}
	## grows or shrinks a given memory block. If p is **nil** then a new
	## memory block is returned. In either way the block has at least
	## ``newSize`` bytes. If ``newSize == 0`` and p is not **nil**
	## ``realloc`` calls ``dealloc(p)``. In other cases the block has to
	## be freed with ``dealloc``.
	## The allocated memory belongs to its allocating thread!
	## Use `reallocShared` to reallocate from a shared heap.
	proc resize*[T](p: ptr T, newSize: Natural): ptr T {.inline, benign.} =
	## grows or shrinks a given memory block. If p is **nil** then a new
	## memory block is returned. In either way the block has at least
	## ``T.sizeof * newSize`` bytes. If ``newSize == 0`` and p is not
	## **nil** ``resize`` calls ``dealloc(p)``. In other cases the block
	## has to be freed with ``free``. The allocated memory belongs to
	## its allocating thread!
	## Use `resizeShared` to reallocate from a shared heap.
	cast[ptr T](realloc(p, T.sizeof * newSize))
	proc dealloc*(p: pointer) {.noconv, rtl, tags: [], benign.}
	## frees the memory allocated with ``alloc``, ``alloc0`` or
	## ``realloc``. This procedure is dangerous! If one forgets to
	## free the memory a leak occurs; if one tries to access freed
	## memory (or just freeing it twice!) a core dump may happen
	## or other memory may be corrupted.
	## The freed memory must belong to its allocating thread!
	## Use `deallocShared` to deallocate from a shared heap.
	proc allocShared*(size: Natural): pointer {.noconv, rtl, benign.}
	## allocates a new memory block on the shared heap with at
	## least ``size`` bytes. The block has to be freed with
	## ``reallocShared(block, 0)`` or ``deallocShared(block)``. The block
	## is not initialized, so reading from it before writing to it is
	## undefined behaviour!
	proc createSharedU*(T: typedesc, size = 1.Positive): ptr T {.inline,
	benign.} =
	## allocates a new memory block on the shared heap with at
	## least ``T.sizeof * size`` bytes. The block has to be freed with
	## ``resizeShared(block, 0)`` or ``freeShared(block)``. The block
	## is not initialized, so reading from it before writing to it is
	## undefined behaviour!
	cast[ptr T](allocShared(T.sizeof * size))
	proc allocShared0*(size: Natural): pointer {.noconv, rtl, benign.}
	## allocates a new memory block on the shared heap with at
	## least ``size`` bytes. The block has to be freed with
	## ``reallocShared(block, 0)`` or ``deallocShared(block)``.
	## The block is initialized with all bytes
	## containing zero, so it is somewhat safer than ``allocShared``.
	proc createShared*(T: typedesc, size = 1.Positive): ptr T {.inline.} =
	## allocates a new memory block on the shared heap with at
	## least ``T.sizeof * size`` bytes. The block has to be freed with
	## ``resizeShared(block, 0)`` or ``freeShared(block)``.
	## The block is initialized with all bytes
	## containing zero, so it is somewhat safer than ``createSharedU``.
	cast[ptr T](allocShared0(T.sizeof * size))
	proc reallocShared*(p: pointer, newSize: Natural): pointer {.noconv, rtl,
	benign.}
	## grows or shrinks a given memory block on the heap. If p is **nil**
	## then a new memory block is returned. In either way the block has at
	## least ``newSize`` bytes. If ``newSize == 0`` and p is not **nil**
	## ``reallocShared`` calls ``deallocShared(p)``. In other cases the
	## block has to be freed with ``deallocShared``.
	proc resizeShared*[T](p: ptr T, newSize: Natural): ptr T {.inline.} =
	## grows or shrinks a given memory block on the heap. If p is **nil**
	## then a new memory block is returned. In either way the block has at
	## least ``T.sizeof * newSize`` bytes. If ``newSize == 0`` and p is
	## not **nil** ``resizeShared`` calls ``freeShared(p)``. In other
	## cases the block has to be freed with ``freeShared``.
	cast[ptr T](reallocShared(p, T.sizeof * newSize))
	proc deallocShared*(p: pointer) {.noconv, rtl, benign.}
	## frees the memory allocated with ``allocShared``, ``allocShared0`` or
	## ``reallocShared``. This procedure is dangerous! If one forgets to
	## free the memory a leak occurs; if one tries to access freed
	## memory (or just freeing it twice!) a core dump may happen
	## or other memory may be corrupted.
	proc freeShared*[T](p: ptr T) {.inline, benign.} =
	## frees the memory allocated with ``createShared``, ``createSharedU`` or
	## ``resizeShared``. This procedure is dangerous! If one forgets to
	## free the memory a leak occurs; if one tries to access freed
	## memory (or just freeing it twice!) a core dump may happen
	## or other memory may be corrupted.
	deallocShared(p)

The create procs are visible, the only apparent difference being the pragmas:
{.noconv, rtl, tags: [], benign.} for allocs and {.inline, benign.} for creates.

[evanperryg-old]

A similar thing seems to exist with functions labeled with the async pragma.

This code:

# foo.nim
import asyncdispatch

proc hello*() {.async.} =
  ## says hello.
  echo "hello, world!"

proc goodbye*() =
  ## says goodbye.
  echo "goodbye, world!"

when run through nim doc on 0.19.2 will show both functions, but will only show the doc text for goodbye. This behavior can also be seen in the missing documentation for readAll in asyncdispatch

[narimiran]

the only apparent difference being the pragmas

Not the only difference.

The other difference (which is the real reason here, from what I can tell) is that procs with generated docs have the body, while the others don't have it.

proc foo =
  ## this will be visible
  discard

proc bar
  ## not visible

---

Maybe related: #10687

[narimiran]

Fixed by #11173