to doc generation
The problem with putting too much information in the code, is that it over
annoys the core developers.
If we look at PHP ( what i consider one of the better & user friendly
documentations ), they only have the basic information with each function but
have a references to a full documentation page. The bulk of the details, the
several examples, comment section etc are separated from the base code
documentation. It keeps the basic documentation in the core files down and
allows more flexibility in regards to the entire page.
Araq seems to dislike having too much documentation junk added to the core
files. And its not hard to understand why. Over time it will make the code less
readable if developers need to jump 50 pages just to get to specific functions.
Unless a person uses a IDE like Intelli/Phpstorm that can fold all
documentation by default ( fat chance as there is no proper nim plugin ). Or
even worse when your using VIM.
think the way to document a Nim library is by example, often via Rosetta
Code
Agree but any example needs to be part of the Nim documentation. Relying upon a
3th party host like Rosetta Code is always taking a risk. Noticed that the
quality of the examples also fluctuates. Its nice when there are multiple
examples for the same task because there are many that roads to lead to Rome.
One issue for instants that can trow people off, is because of the flexibility
that is Nim. When people see a example as:
import strutils
let text = "Hello,How,Are,You,Today"
//a
echo join(text.split(','), " ")
//b
echo join(split(text, ','), " ")
Both do the same. But if one function example uses (A) and one function example
uses (B), it only increases people there confusion. Unless like above both or
multiple variations are shown. So people understand better. Flexibility comes
at a cost of needing more documentation / examples, if the goal is to keep
things "newbie" friendly.
* * *
My suggestion: PHP style documentation. Basic information in the code + a
reference link for more details. The reference link points to a **wiki
documentation system** on the nim website. This way allowing people to enhance
the documentation without people fiddling with the core files.
It also removes work from the developers there hands. Disadvantage: there is a
need to a few permanent moderators that can undo bad or incorrect changes. Add
bonus, it also makes the project seem more "open".
