Documentation for modules like db_sqlite3 feels very sparse and not very newbie friendly. I'm interested in finding out how the documentation generation works, but haven't found it documented. I see it seems to be a javadoc like system where comments seem to be thrown into an html file.
So I can go to lib/impure and write nimrod doc2 db_sqlite.nim to generate some html files (koch web seems a bit too big to rebuild a single html file) . The comments seem formatted in reStructuredText for easy direct output, so I guess it's impossible to change the output generator unless reusing the same input syntax, and there are no special features like source code highlighting for example blocks with hyperlinks between procs (one calling/naming another in the example and generating an html link to it).
Thinking about improving on db_sqlite as example for myself I saw it would be really ugly to have to reorder the whole file so that procs like Open/Close come first and are easier to find for a newcomer. I couldn't find either a way of groupping procs, like proc1/2/3 go into this group with a separate documentation introductionand proc4/5/6 are later, etc.
I also noted files tend to have trailing whitespace characters in proc lines, but not consistently, so I guess this is not a rule but rather the author's (unaware?) doing.
In general I find documentation made out of embedded comments to be useful only to other developers: they have a direct audience, the docs are near, they specify stuff not needed/wanted by an outsider and can be more concise. End user documentation seems better in a separate package were long descriptions and examples can be formatted properly without requiring huge changes to the source itself (like reordering the procs to get a different order).
So in the end I'm not willing to start hacking on db_sqlite.nim for the sake of documenting stuff if that's not really going to fit with the style of the rest of the code/docs and maybe it would be better to write manually an external doc/db_sqlite.txt in rst format which would then override the one generated by the source code.
What are your opinions on the documentation itself. I think I'll go and write a separate experimental documentation for db_sqlite, otherwise it might be hard to compare something intangible (my thoughts) to already existing docs.