Proper documentation for all vlib modules

[danieldaeschle]

Follow our own godoc inspired guidelines (vdoc guidelines) and: https://blog.golang.org/godoc

You can use v missdoc <path> to get a detailed list of functions that miss documentation.

List of files which need to be documented properly:

vlib

• vlib/benchmark/benchmark.v
• vlib/bitfield/bitfield.v
• vlib/builtin/array.v
• vlib/builtin/bare/.checks/checks.v
• vlib/builtin/bare/.checks/consts/consts.v
• vlib/builtin/bare/.checks/forkedtest/forkedtest.v
• vlib/builtin/bare/.checks/linuxsys/linuxsys.v
• vlib/builtin/bare/.checks/string/string.v
• vlib/builtin/bare/.checks/structs/structs.v
• vlib/builtin/bare/builtin_bare.v
• vlib/builtin/bare/linuxsys_bare.v
• vlib/builtin/bare/mm_bare.v
• vlib/builtin/bare/string_bare.v
• vlib/builtin/builtin.v
• vlib/builtin/builtin.c.v
• vlib/builtin/builtin_nix.c.v
• vlib/builtin/builtin_windows.c.v
• vlib/builtin/chan.v
• vlib/builtin/float.v
• vlib/builtin/int.v
• vlib/builtin/js/builtin.v
• vlib/builtin/map.v
• vlib/builtin/option.v
• vlib/builtin/rune.v
• vlib/builtin/sorted_map.v
• vlib/builtin/string.v
• vlib/builtin/utf8.v
• vlib/cli/command.v
• vlib/cli/flag.v
• vlib/cli/help.v
• vlib/cli/version.v
• vlib/clipboard/clipboard_darwin.c.v
• vlib/clipboard/clipboard_linux.c.v
• vlib/clipboard/clipboard_solaris.c.v
• vlib/clipboard/clipboard_windows.c.v
• vlib/crypto/aes/aes.v
• vlib/crypto/aes/aes_cbc.v
• vlib/crypto/md5/md5.v
• vlib/crypto/rand/rand_linux.c.v
• vlib/crypto/rand/rand_solaris.c.v
• vlib/crypto/rand/utils.v
• vlib/crypto/sha1/sha1.v
• vlib/crypto/sha256/sha256.v
• vlib/crypto/sha512/sha512.v
• vlib/encoding/base64/base64.v
• vlib/encoding/base32/base32.v
• vlib/encoding/binary/binary.v
• vlib/encoding/csv/reader.v
• vlib/encoding/csv/writer.v
• vlib/encoding/utf8/utf8.v
• vlib/eventbus/eventbus.v
• vlib/flag/flag.v
• vlib/fontstash/fontstash.v
• vlib/gg/gg.v
• vlib/gg/image.v
• vlib/gg/text_rendering.v
• vlib/gx/color.v
• vlib/gx/image.v
• vlib/gx/text.v
• vlib/hash/crc32/crc32.v
• vlib/hash/fnv1a/fnv1a.v
• vlib/hash/wyhash.v
• vlib/hash/wyhash.c.v
• vlib/io/readerwriter.v
• vlib/io/util/util.v
• vlib/json/json_primitives.v
• vlib/live/executable/reloader.v
• vlib/log/log.v
• vlib/math/big/big.v
• vlib/math/complex/complex.v
• vlib/math/factorial/factorial.v
• vlib/math/fractions/fraction.v
• vlib/math/math.v
• vlib/mysql/enums.v
• vlib/mysql/result.v
• vlib/mysql/utils.v
• vlib/net/address.v
• vlib/net/errors.v
• vlib/net/ftp/ftp.v
• vlib/net/html/data_structures.v
• vlib/net/html/dom.v
• vlib/net/html/parser.v
• vlib/net/html/tag.v
• vlib/net/http/chunked/dechunk.v
• vlib/net/http/cookie.v
• vlib/net/http/download_nix.c.v
• vlib/net/http/download_windows.c.v
• vlib/net/http/http.v
• vlib/net/http/method.v
• vlib/net/http/status.v
• vlib/net/net_nix.c.v
• vlib/net/net_windows.c.v
• vlib/net/openssl/c.v
• vlib/net/smtp/smtp.v
• vlib/net/tcp.v
• vlib/net/udp.v
• vlib/net/urllib/urllib.v
• vlib/os/fd.v
• vlib/os/file.v
• vlib/os/os.v
• vlib/os/os_android.c.v
• vlib/os/os_linux.c.v
• vlib/os/os_nix.c.v
• vlib/os/os_windows.c.v
• vlib/os/process.v
• vlib/os/process_nix.c.v
• vlib/os/process_windows.c.v
• vlib/os2/os2_darwin.c.v
• vlib/pg/pg.v
• vlib/picoev/picoev.v
• vlib/picohttpparser/misc.v
• vlib/picohttpparser/picohttpparser.v
• vlib/picohttpparser/request.v
• vlib/picohttpparser/response.v
• vlib/rand/mt19937/mt19937.v
• vlib/rand/musl/musl_rng.v
• vlib/rand/rand.v
• vlib/readline/readline_linux.c.v
• vlib/regex/regex.v
• vlib/runtime/runtime.v
• vlib/runtime/runtime_nix.c.v
• vlib/runtime/runtime_windows.c.v
• vlib/semver/compare.v
• vlib/semver/parse.v
• vlib/semver/range.v
• vlib/semver/semver.v
• vlib/semver/util.v
• vlib/sokol/audio/audio.v
• vlib/sokol/gfx/gfx.v
• vlib/sokol/gfx/gfx_structs.v
• vlib/sokol/gfx/gfx_utils.v
• vlib/sokol/sapp/sapp.v
• vlib/sokol/sapp/sapp_structs.v
• vlib/sokol/sfons/sfons.v
• vlib/sokol/sgl/sgl.v
• vlib/sqlite/sqlite.v
• vlib/stbi/stbi.v
• vlib/strconv/atof.v
• vlib/strconv/f32_str.v
• vlib/strconv/f64_str.v
• vlib/strconv/format.v
• vlib/strconv/ftoa.v
• vlib/strconv/utilities.v
• vlib/strings/builder.js.v
• vlib/strings/builder.v
• vlib/strings/strings.js.v
• vlib/sync/bench/channel_bench_v.v
• vlib/sync/bench/many_writers_and_receivers_on_1_channel.v
• vlib/sync/channels.v
• vlib/sync/pool.v
• vlib/sync/sync_nix.c.v
• vlib/sync/sync_windows.c.v
• vlib/sync/waiter_nix.c.v
• vlib/sync/waiter_windows.c.v
• vlib/sync/waitgroup.v
• vlib/szip/szip.v
• vlib/term/control.v
• vlib/term/term.v
• vlib/term/ui/ui.v
• vlib/term/colors.v
• vlib/term/ui/input_nix.c.v
• vlib/term/ui/input_windows.c.v
• vlib/term/ui/termios_nix.c.v
• vlib/term/ui/ui.v
• vlib/time/stopwatch.v
• vlib/time/time.v
• vlib/time/time_darwin.c.v
• vlib/time/time_linux.c.v
• vlib/time/time_nix.c.v
• vlib/time/time_solaris.c.v
• vlib/time/time_windows.c.v
• vlib/time/unix.v
• vlib/v/ast/ast.v
• vlib/v/ast/scope.v
• vlib/v/ast/str.v
• vlib/v/builder/builder.v
• vlib/v/builder/c.v
• vlib/v/builder/cc.v
• vlib/v/builder/cflags.v
• vlib/v/builder/compile.v
• vlib/v/builder/iosplist.v
• vlib/v/builder/js.v
• vlib/v/builder/msvc.v
• vlib/v/builder/x64.v
• vlib/v/cflag/cflags.v
• vlib/v/checker/check_types.v
• vlib/v/checker/checker.v
• vlib/v/depgraph/depgraph.v
• vlib/v/doc/doc.v
• vlib/v/doc/module.v
• vlib/v/doc/node.v
• vlib/v/doc/utils.v
• vlib/v/eval/eval.v
• vlib/v/fmt/fmt.v
• vlib/v/gen/auto_str_methods.v
• vlib/v/gen/cgen.v
• vlib/v/gen/cmain.v
• vlib/v/gen/comptime.v
• vlib/v/gen/ctempvars.v
• vlib/v/gen/fn.v
• vlib/v/gen/js/js.v
• vlib/v/gen/js/jsdoc.v
• vlib/v/gen/json.v
• vlib/v/gen/live.v
• vlib/v/gen/profile.v
• vlib/v/gen/sql.v
• vlib/v/gen/str.v
• vlib/v/gen/x64/elf.v
• vlib/v/gen/x64/elf_obj.v
• vlib/v/gen/x64/gen.v
• vlib/v/parser/assign.v
• vlib/v/parser/comptime.v
• vlib/v/parser/containers.v
• vlib/v/parser/fn.v
• vlib/v/parser/if_match.v
• vlib/v/parser/lock.v
• vlib/v/parser/module.v
• vlib/v/parser/parse_type.v
• vlib/v/parser/parser.v
• vlib/v/parser/pratt.v
• vlib/v/parser/sql.v
• vlib/v/parser/struct.v
• vlib/v/pkgconfig/main.v
• vlib/v/pkgconfig/pkgconfig.v
• vlib/v/pref/default.v
• vlib/v/pref/os.v
• vlib/v/pref/pref.v
• vlib/v/pref/should_compile.v
• vlib/v/scanner/scanner.v
• vlib/v/table/attr.v
• vlib/v/table/table.v
• vlib/v/table/types.v
• vlib/v/token/position.v
• vlib/v/token/token.v
• vlib/v/util/diff.v
• vlib/v/util/errors.v
• vlib/v/util/quote.v
• vlib/v/util/scanning.v
• vlib/v/util/suggestions.v
• vlib/v/util/util.v
• vlib/v/vcache/vcache.v
• vlib/v/vmod/parser.v
• vlib/v/vmod/vmod.v
• vlib/vweb/assets/assets.v
• vlib/vweb/tmpl/tmpl.v
• vlib/vweb/vweb.v
• vlib/x/json2/decoder.v
• vlib/x/openssl/openssl.v
• vlib/x/websocket/events.v
• vlib/x/websocket/handshake.v
• vlib/x/websocket/io.v
• vlib/x/websocket/message.v
• vlib/x/websocket/uri.v
• vlib/x/websocket/utils.v
• vlib/x/websocket/websocket_client.v
• vlib/x/websocket/websocket_nix.c.v
• vlib/x/websocket/websocket_server.v
• vlib/x/websocket/websocket_windows.c.v

cmd

• cmd/tools/vself.v
• cmd/tools/vcomplete.v
• cmd/tools/vdoctor.v
• cmd/tools/fast/fast.v
• cmd/tools/vtest-fmt.v
• cmd/tools/vfmt.v
• cmd/tools/modules/testing/common.v
• cmd/tools/modules/scripting/scripting.v
• cmd/tools/modules/vhelp/vhelp.v
• cmd/tools/modules/vgit/vgit.v
• cmd/tools/gen_vc.v
• cmd/tools/oldv.v
• cmd/tools/vsymlink.v
• cmd/tools/repeat.v
• cmd/tools/performance_compare.v
• cmd/tools/gen1m.v
• cmd/tools/vtest-cleancode.v
• cmd/tools/vpm.v
• cmd/tools/vbuild-tools.v
• cmd/tools/vdoc.v
• cmd/tools/test_os_process.v
• cmd/tools/vvet.v
• cmd/tools/vtest-compiler.v
• cmd/tools/check_os_api_parity.v
• cmd/tools/vup.v
• cmd/tools/check-md.v
• cmd/tools/preludes/tests_assertions.v
• cmd/tools/preludes/tests_with_stats.v
• cmd/tools/vcreate.v
• cmd/tools/vrepl.v
• cmd/tools/vbin2v.v
• cmd/v/v.v

[larpon]

I have collected this list of functions that miss documentation using this little tool I wrote

[danieldaeschle]

Can you paste the files as a markdown check list?

[larpon]

I'll see what I can do tomorrow

[JalonSolov]

Do you want just the modules, or the files in the modules?

[danieldaeschle]

Maybe all files listed.

[JalonSolov]

Ok. Using Larpon's list and a few regex search/replace operations, I've edited your first comment with the list of 255 files that need docs.

[larpon]

Mind you that the list is just vlib. The examples (and tutorials?) could maybe use a few comments as well. But vlib is ofc the most important.
Thanks for the help @JalonSolov !

[JalonSolov]

I'd leave out */tests/* and thirdparty/* (I removed files in tests subdirs from your list... a bunch of them just had a single function named f anyway). Examples? Maybe.

Definitely need to add cmd/* files.

[larpon]

I'd leave out */tests/* and thirdparty/* (I removed files intestssubdirs from your list... a bunch of them just had a single function named f anyway). Examples? Maybe.

Definitely need to add cmd/* files.

Good thinking 🙂

[helto4real]

@danieldaeschle the #7078 should take care of the x.websocket docs. Add checkmark on those?

[Delta456]

I am interested in helping!

[danieldaeschle]

@helto4real i left a comment there. Not all comments were by our guideline. Please fix it, then i will checkmark it.

[Delta456]

@danieldaeschle I think you should show an example of how to document at the OP as it will make it clear.

[danieldaeschle]

From the godoc link:
Notice this comment is a complete sentence that begins with the name of the element it describes. This important convention allows us to generate documentation in a variety of formats, from plain text to HTML to UNIX man pages, and makes it read better when tools truncate it for brevity, such as when they extract the first line or sentence.

This would be a good comment:

// foo does nothing special because it's only an example
fn foo() {...}

[helto4real]

@danieldaeschle not sure how I did not follow it? I read the go docs and think I fix them. Can you comment an example where it was not done the correct way? I am happy to fix it but not sure what :)

[danieldaeschle]

Sorry for being too implicit. I commented some lines (not all, you need to fix the others as well).

[helto4real]

Sorry for being too implicit. I commented some lines (not all, you need to fix the others as well).

Ohh right this is why we need review... Easy to get "blind" of your own code. Thansk for clearing that up. Will make a new PR and add you as reviewer if you please would help out with this @danieldaeschle .

[larpon]

I have checked with my tool - and it reports no missing comments for public functions in x/websocket.
Also check our own docs - where I had to elaborate on a few things recently :)

[larpon]

@Delta456 - I've updated OP with a link to our own guidelines (maybe need rephrasing, but now it's there).

[danieldaeschle]

I have checked with my tool - and it reports no missing comments for public functions in x/websocket.
Also check our own docs - where I had to elaborate on a few things recently :)

because the "faulty" comments are merged now

[larpon]

@danieldaeschle - yeah - I had to re-read that - I've reverted the checkmarks I edited :)
Also ran my tool in cmd/ - not many pub fn in them - but plenty of undocumented normal fn <...>'s
I'll add them to the list as well

[spytheman]

@larpon can I add a slightly modified version of your tool under cmd/tools/ ?
The main change is that it produces results in the common file:line:col: format, and it processes multiple paths, so you can do:
./v run cmd/tools/missdoc.v vlib/bitfield/ vlib/flag/
... and get results like these:

/v/pv/vlib/bitfield/bitfield.v:76:0:pub fn del(instance *BitField)
/v/pv/vlib/bitfield/bitfield.v:446:0:fn bitmask(bitnr int) u32
/v/pv/vlib/bitfield/bitfield.v:450:0:fn bitslot(size int) int
/v/pv/vlib/bitfield/bitfield.v:454:0:fn min(input1 int, input2 int) int
/v/pv/vlib/bitfield/bitfield.v:463:0:fn zbitnslots(length int) int
/v/pv/vlib/flag/flag.v:13:0:pub fn (f Flag) str() string
/v/pv/vlib/flag/flag.v:18:0:pub fn (af []Flag) str() string
/v/pv/vlib/flag/flag.v:315:0:pub fn (mut fs FlagParser) limit_free_args_to_at_least(n int)
/v/pv/vlib/flag/flag.v:325:0:pub fn (mut fs FlagParser) limit_free_args_to_exactly(n int)
/v/pv/vlib/flag/flag.v:346:0:pub fn (mut fs FlagParser) arguments_description(description string)

[larpon]

@spytheman yes, no problem - it's just a 3 min. hack 😄
(Cool additions)

[spytheman]

Thanks.

[spytheman]

Added in f786177.
3 min. hack or not, it is a very useful tool, so thanks again @larpon!

[wahur666]

Since my last rewrite of the documentation collector, the list may needs updating. I wrote a nice Powershell command if you want to get the remaining files.

.\v.exe missdoc .\vlib\ | ForEach-Object {$_.Split(":")[0] + ":" + $_.Split(":")[1]} | Get-Unique | Resolve-Path -Relative | ForEach-Object {$_.Substring(2)}

[dotdot0]

Can someone guide me how can I start writing docs?

[JalonSolov]

https://github.com/vlang/v/blob/master/doc/docs.md#writing-documentation