Nim uses a lot of procs overloading to create variations of an algorithm for
different parameters. When one wants to document that algorithm, for a public
overloaded proc, one has to repeat the documentation for all variants. And
that's not efficient...
Is there a way to factor documentation for overloaded procedures? If not, what
would you suggest to enhance Nim's source code and documentation?
For instance, how would be the way to factor the documentation comments in that
fake sample code?
## This module provides base operations on matrices and vectors.
## =============================================================
type
Matrix* = object
Vector* = object
## Addition on matrices and vectors.
## ---------------------------------
## Addition adds each item of the first matrix or vector to the
## corresponding item (same row, same column) of the second matrix.
##
## Example
##
## .. code-block:: nim
##
## let
## v1 = makeVector(5, [1, 2, 3, 4, 5])
## v2 = makeVector(5, [6, 7, 8, 9, 0])
## m1 = makeMatrix(2, 3, [[1, 2, 3], [4, 5, 6]])
## m2 = makeMatrix(2, 3, [[6, 7, 8], [9, 0, 1]])
##
## echo "v1 + v2 = ", (v1 + v2)
## echo "m1 + m2 = ", (m1 + m2)
##
## Output:
##
## .. code-block:: nim
##
## v1 + v2 = [7, 9, 11, 13, 5]
## m1 + m2 = [[7, 9, 11], [13, 5, 7]]
##
proc `+`*(a, b: Matrix): Matrix =
## Add two matrices ``a`` and ``b``.
## The matrices must have compatible dimensions.
discard
proc `+`*(a, b: Vector): Vector =
## Add two vectors.
## The vectors must be of the same type and dimensions.
discard
## String representation
## ---------------------
## Matrices and vectors are converted to string with the ``$`` operator.
## They are represented as arrays or values for vectors and arrays of arrays
## for matrices, even if the internal representation is different, so these
## strings can be used to initialise new vectors or matrices.
##
## Example
## ...
proc `$`*(a: Matrix): string =
## Create a string representation of the matrix ``a``.
discard
proc `$`*(a: Vector): string =
## Create a string representation of the vector ``a``.
discard
>From what I understand, the current `nim doc` collects all global comments and
>put them in the introduction of the documentation. I think it would be usefull
>to have a way to specify that a global comment is related to a group of
>overloaded procs. I would expect the generated documentation to present
>overloaded procs in the same sections with the preceding header documentation.
Also, this would allow to shorten the index of procs. For the current example,
the Procs index contains 4 entries:
**Procs**
* `+`
* `+`
* `$`
* `$`
This could be reduced to only the unique names and the links refering to the
header documentation for the overloaded procs. As the index does not present
the parameters, the reader can't discriminate between the entries and the index
is a bit of useless.
What do you think?
\--
Pierre
