Nim (and nimsuggest) support documentation comments for procedures, but I haven't seen anything for parameters. Visual Studio supports this, example for C#: https://raw.githubusercontent.com/Gravityzwell/NimStudio/master/wiki/img/paramdoc.png
I'd be glad to add support to NimStudio if there is a way. Maybe just match the parameter name if it's the first word after ##: ## proc help 1 ## proc help 2 ## param1 help for param1
Hi @GravityWell,
I also haven't seen any specific support for parameters. We know that Nim uses RST for documentation, but looking through the docs for the system module (for example), it's evident that parameters are mentioned in an arbitrary fashion in the doc for a procedure.
The use of markup also seems to be arbitrary (and slightly erratic):
- Proc ze64 uses italic for the parameter name x.
- Procs incl and card use bold for the parameter name x (the set).
- The template incl uses bold for the parameter name x (the set), even though the parameter in the prototype is actually called s.
I think it would also be very sensible to make it integrate with the existing Nim DocGen tools.
Looking at your Visual Studio paramdoc.png screenshot, the syntax looks more verbose and XML-laden than I think is necessary, especially to document a parameter:
<param name="startindex">startindex help</param>
From my C++, days, I recall that doxygen markup for code documentation was quite useful and not too verbose. For example, to document a parameter 'dest' in doxygen:
@param dest The memory area to copy to.
The doxygen docs for @param state that doxygen also checks for the existence of the listed parameter:
The existence of the parameter is checked and a warning is given if the documentation of this (or any other) parameter is missing or not present in the function declaration or definition.
As an aside: It's probably not directly useful to you, but a few months ago, I created a Nim module 'docstrings' that provides Python-like docstrings inside a proc. This module is part of my work-in-progress Python-bindings-for-Nim autogenerator (which I'll open source soon, as soon as I have some time to extract it from my larger proprietary codebase).
In this autogenerator, I have a macro (supported by a handful of compile-time procs) that performs step 2 above (extract a list of all parameters & types from the proc prototype in the code) so I can auto-map Nim proc parameter types to Python C-API types. I'm happy to share the code if that will help. (Or perhaps it's more sensible to go through an official nimsuggest API or something like that.)
I can't find any sign of a Nim library to parse doxygen markup.
If you end up starting on such a doxygen parser (or you find one), can you make it a stand-alone module (or point me to it), and I'll happily use it too in nim-docstrings. :)
proc createFoo(bar: Bar; x, y: int): Foo =
## Creates Foo from Bar with coords x and y.
##
## @param bar The Bar to create Foo from.
## @param x The x coordinate as an int.
## @param y The y coordinate as an int.Which is a redundant piece of junk that seems to suggest I cannot read type signatures.
Hi @Araq,
Sure, but that's because the programmer wrote pointless @param info. It's no more an argument against parameter-specific notes than
# ----------------------------------------------
# Increment the value of the variable named `i`.
# ----------------------------------------------
i = i + 2
Here's the angle I'm coming from: If I feed my Python-wrapper-autogenerator a Nim proc that looks like this:
proc myfunc1*(x: int, y: string, z: float64): ptr PyArrayObject {.exportpy.} =
docstring"""This is a Python-style docstring!
It doesn't do anything by itself, but it can be extracted by pragmas
(like the `exportpy` pragma, for example) that process this proc.
"""
# Some Nim code that creates a `ptr PyArrayObject` result.
# Left as an exercise to the reader.
then in addition to a C-API wrapper function, my autogenerator will also generate a Python-style __doc__ for the wrapper function, that can be viewed in the Python interpreter when you use help(mymod.myfunc1):
myfunc1(...)
myfunc1(x: int, y: str, z: float) -> numpy.ndarray
Parameters
----------
x : int -> int
y : str -> string
z : float -> float64
Returns
-------
out : numpy.ndarray <- ptr PyArrayObject
This is a Python-style docstring!
It doesn't do anything by itself, but it can be extracted by pragmas
(like the `exportpy` pragma, for example) that process this proc.
(Yes, this autogenerated __doc__ lists the parameter types again in the vertical "Parameters" summary, but that's because I was mimicking the Numpy documentation style.)
It's been on my distant TODO list, to implement extraction of parameter-specific notes from docstrings, so they can be included in these autogenerated Python docs in the "Parameters" summary.
Of course, it's even better if the syntax is the same as the de facto standard for Nim parameter-specific syntax (whatever it may be).
nimsuggest supports invocation information via the con command. In general sug is for ., con is for (.
What is nimsuggest "use"? I've tried to track down what that does, but so far I don't understand it.
I agree with jboy. Because someone might enter pointless comments (which I also strongly dislike), I don't think that's a rationale to exclude the capability.
Because someone might enter pointless comments (which I also strongly dislike), I don't think that's a rationale to exclude the capability.
It is a rationale because it's always redundant as the language already makes you give parameters a name and a type. The argument is not "bad code can result from it", but "bad code results from it in 90% of all cases". :P
Setting aside parameter help (although I'm not done yet! ;-) ), is there a way to have nimsuggest con,sug return parameter names? Currently it only seems to return their types.
Using strutils.replace as an example: https://github.com/Gravityzwell/NimStudio/wiki/Intellisense
It could be showing:
(replace_this string, with_this string)
Consider it done.
Thanks! I added an issue here for reference:
https://github.com/Araq/Nim/issues/2520
nimsuggest - return parameter names for sug, con, def