> but I don't like putting the documentation right in the body of the function
Indeed, I regard that as very ugly! Because it separates function signature with its parameter definition from proc body. For small progs that is already an ugly interruption of whole proc unit and interrupts flow of reading, and for larger procs with longer documentation it leads to the fact, that procedure header and full body does not fit on screen (without scrolling). But this style was present already 5 years ago when I started with Nim, so I think there is no chance to change it, and I assume that automatic doc generation is much easier when documentation is after proc header. But indeed I find it so ugly that I never used that style till now -- I write no doc comment at all or put it in front of the header, knowing that Nim's doc generator may not work. Araq may tell us that we should use a smart editor which can display doc above proc header but save it to file below header. Yes such editors may be possible, but my dumb GTKSourceView one does not support it. But that feature may be a good reason to change my editor, maybe to one supporting LSP (lang server protocol) added recently by PMunch.
