close
The Wayback Machine - https://web.archive.org/web/20210825100614/https://github.com/nim-lang/Nim/issues/14736
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Missing docs in system #14736

Open
konsumlamm opened this issue Jun 19, 2020 · 1 comment
Open

Missing docs in system #14736

konsumlamm opened this issue Jun 19, 2020 · 1 comment

Comments

@konsumlamm
Copy link
Contributor

@konsumlamm konsumlamm commented Jun 19, 2020

There are some undocumented procs in the system module (the links are for the devel docs):

@timotheecour
Copy link
Member

@timotheecour timotheecour commented Jun 20, 2020

@konsumlamm pretty please: consider sending PR's instead; too many bugs to keep track of and this falls under the umbrella "docs should improve"

I would start with the procs that would benefit most from having doc comment, especially if there's some gotcha; and I'd focus on the gotchas to make the docs useful and not redundant

  • <= seems low priority (compared to other procs) as it should be obvious, no gotcha;
  • * has a gotcha so is worth mentioning (eg; overflow checks with signed integers)
  • cas is a terrible non-descriptive name for a proc defined in system (and probably shouldn't be in system but in some other module); either way a doc comment helps here (and maybe deprecating it later)
  • use runnableExamples as needed; often an example is the simplest / most concise explanation
  • how about start with these one:
proc `|`(a, b: typedesc): typedesc =
  runnableExamples: doAssert int is float | int
  • start with just 1 or a few at first just to get some feedback before doing more

oh, and thanks for #14737 ; I will follow-up there

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants