Confusing pairs create/dealloc, createShared/freeShared

[mratsim]

Looking at the current system documentation the typed alloc/free pairs are confusing:

alloc/create --> dealloc

Nim/lib/system.nim

Lines 2397 to 2423 in 4e0f120

	proc alloc*(size: Natural): pointer {.noconv, rtl, tags: [], benign, raises: [].}
	## Allocates a new memory block with at least ``size`` bytes.
	##
	## The block has to be freed with `realloc(block, 0) <#realloc,pointer,Natural>`_
	## or `dealloc(block) <#dealloc,pointer>`_.
	## 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 <#allocShared,Natural>`_ to allocate from a shared heap.
	##
	## See also:
	## * `alloc0 <#alloc0,Natural>`_
	proc createU*(T: typedesc, size = 1.Positive): ptr T {.inline, benign, raises: [].} =
	## Allocates a new memory block with at least ``T.sizeof * size`` bytes.
	##
	## The block has to be freed with `resize(block, 0) <#resize,ptr.T,Natural>`_
	## or `dealloc(block) <#dealloc,pointer>`_.
	## 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 <#createSharedU,typedesc>`_ to allocate from a shared heap.
	##
	## See also:
	## * `create <#create,typedesc>`_
	cast[ptr T](alloc(T.sizeof * size))

dealloc <--> alloc

Nim/lib/system.nim

Lines 2473 to 2483 in 4e0f120

	proc dealloc*(p: pointer) {.noconv, rtl, tags: [], benign, raises: [].}
	## 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 <#deallocShared,pointer>`_ to deallocate from a shared heap.

allocShared <--> deallocShared

Nim/lib/system.nim

Lines 2485 to 2497 in 4e0f120

	proc allocShared*(size: Natural): pointer {.noconv, rtl, benign, raises: [].}
	## Allocates a new memory block on the shared heap with at
	## least ``size`` bytes.
	##
	## The block has to be freed with
	## `reallocShared(block, 0) <#reallocShared,pointer,Natural>`_
	## or `deallocShared(block) <#deallocShared,pointer>`_.
	##
	## The block is not initialized, so reading from it before writing
	## to it is undefined behaviour!
	##
	## See also:
	## `allocShared0 <#allocShared0,Natural>`_.

createShared <--> freeShared

Nim/lib/system.nim

Lines 2525 to 2536 in 4e0f120

	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) <#resizeShared,ptr.T,Natural>`_ or
	## `freeShared(block) <#freeShared,ptr.T>`_.
	##
	## The block is initialized with all bytes
	## containing zero, so it is somewhat safer than
	## `createSharedU <#createSharedU,typedesc>`_.
	cast[ptr T](allocShared0(T.sizeof * size))

The confusion

create does not have a free to pair with, unlike createShared.
Also while create refers to dealloc in the documentation, dealloc only refers to alloc.