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

[x] vlib/benchmark/benchmark.v
[x] vlib/bitfield/bitfield.v
[x] 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
[x] vlib/builtin/builtin.v
[x] vlib/builtin/builtin.c.v
[ ] vlib/builtin/builtin_nix.c.v
[ ] vlib/builtin/builtin_windows.c.v
[x] vlib/builtin/chan.v
[x] vlib/builtin/float.v
[x] vlib/builtin/int.v
[ ] vlib/builtin/js/builtin.v
[ ] vlib/builtin/map.v
[x] vlib/builtin/option.v
[ ] vlib/builtin/rune.v
[ ] vlib/builtin/sorted_map.v
[x] vlib/builtin/string.v
[ ] vlib/builtin/utf8.v
[x] vlib/cli/command.v
[x] vlib/cli/flag.v
[x] vlib/cli/help.v
[x] vlib/cli/version.v
[x] vlib/clipboard/clipboard_darwin.c.v
[x] vlib/clipboard/clipboard_linux.c.v
[x] vlib/clipboard/clipboard_solaris.c.v
[x] vlib/clipboard/clipboard_windows.c.v
[x] vlib/crypto/aes/aes.v
[x] vlib/crypto/aes/aes_cbc.v
[x] vlib/crypto/md5/md5.v
[x] vlib/crypto/rand/rand_linux.c.v
[x] vlib/crypto/rand/rand_solaris.c.v
[x] vlib/crypto/rand/utils.v
[x] vlib/crypto/sha1/sha1.v
[x] vlib/crypto/sha256/sha256.v
[x] vlib/crypto/sha512/sha512.v
[x] vlib/encoding/base64/base64.v
[x] vlib/encoding/base32/base32.v
[x] vlib/encoding/binary/binary.v
[x] vlib/encoding/csv/reader.v
[x] vlib/encoding/csv/writer.v
[x] vlib/encoding/utf8/utf8.v
[ ] vlib/eventbus/eventbus.v
[x] vlib/flag/flag.v
[ ] vlib/fontstash/fontstash.v
[x] vlib/gg/gg.v
[x] vlib/gg/image.v
[x] vlib/gg/text_rendering.v
[x] vlib/gx/color.v
[x] vlib/gx/image.v
[x] vlib/gx/text.v
[x] vlib/hash/crc32/crc32.v
[x] vlib/hash/fnv1a/fnv1a.v
[x] vlib/hash/wyhash.v
[x] vlib/hash/wyhash.c.v
[x] vlib/io/readerwriter.v
[x] vlib/io/util/util.v
[ ] vlib/json/json_primitives.v
[ ] vlib/live/executable/reloader.v
[x] 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
[x] vlib/net/ftp/ftp.v
[ ] vlib/net/html/data_structures.v
[x] vlib/net/html/dom.v
[x] vlib/net/html/parser.v
[x] 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
[x] vlib/net/http/http.v
[x] vlib/net/http/method.v
[x] 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
[x] vlib/rand/mt19937/mt19937.v
[x] vlib/rand/musl/musl_rng.v
[x] vlib/rand/rand.v
[ ] vlib/readline/readline_linux.c.v
[x] vlib/regex/regex.v
[x] vlib/runtime/runtime.v
[x] vlib/runtime/runtime_nix.c.v
[x] vlib/runtime/runtime_windows.c.v
[x] vlib/semver/compare.v
[x] vlib/semver/parse.v
[x] vlib/semver/range.v
[x] vlib/semver/semver.v
[x] 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
[x] vlib/strconv/atof.v
[x] vlib/strconv/f32_str.v
[x] vlib/strconv/f64_str.v
[x] vlib/strconv/format.v
[x] vlib/strconv/ftoa.v
[x] 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
[x] vlib/term/control.v
[x] vlib/term/term.v
[x] vlib/term/ui/ui.v
[x] vlib/term/colors.v
[x] vlib/term/ui/input_nix.c.v
[x] vlib/term/ui/input_windows.c.v
[x] vlib/term/ui/termios_nix.c.v
[x] vlib/term/ui/ui.v
[x] vlib/time/stopwatch.v
[x] vlib/time/time.v
[x] vlib/time/time_darwin.c.v
[x] vlib/time/time_linux.c.v
[x] vlib/time/time_nix.c.v
[x] vlib/time/time_solaris.c.v
[x] vlib/time/time_windows.c.v
[x] 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
[x] vlib/v/doc/doc.v
[x] vlib/v/doc/module.v
[x] vlib/v/doc/node.v
[x] 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
[x] vlib/x/websocket/events.v
[x] vlib/x/websocket/handshake.v
[x] vlib/x/websocket/io.v
[x] vlib/x/websocket/message.v
[x] vlib/x/websocket/uri.v
[x] vlib/x/websocket/utils.v
[x] vlib/x/websocket/websocket_client.v
[ ] vlib/x/websocket/websocket_nix.c.v
[x] 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

Nov 30 '20 14:11 danieldaeschle

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

Nov 30 '20 16:11 larpon

Can you paste the files as a markdown check list?

Nov 30 '20 16:11 danieldaeschle

I'll see what I can do tomorrow

Nov 30 '20 18:11 larpon

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

Nov 30 '20 19:11 JalonSolov

Maybe all files listed.

Nov 30 '20 19:11 danieldaeschle

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.

Nov 30 '20 19:11 JalonSolov

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 !

Nov 30 '20 19:11 larpon

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.

Nov 30 '20 19:11 JalonSolov

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 🙂

Nov 30 '20 20:11 larpon

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

Dec 02 '20 10:12 helto4real

I am interested in helping!

Dec 02 '20 10:12 Delta456

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

Dec 02 '20 10:12 danieldaeschle

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

Dec 02 '20 11:12 Delta456

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() {...}

Dec 02 '20 11:12 danieldaeschle

@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 :)

Dec 02 '20 11:12 helto4real

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

Dec 02 '20 11:12 danieldaeschle

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 .

Dec 02 '20 11:12 helto4real

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 :)

Dec 02 '20 12:12 larpon

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

Dec 02 '20 12:12 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 :)

because the "faulty" comments are merged now

Dec 02 '20 12:12 danieldaeschle

@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

Dec 02 '20 12:12 larpon

@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)

Dec 05 '20 09:12 spytheman

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

Dec 05 '20 10:12 larpon

Thanks.

Dec 05 '20 10:12 spytheman

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

Dec 05 '20 10:12 spytheman

Added documentation for v.doc: #7161

Dec 06 '20 09:12 nedpals

Added documentation for net.html: https://github.com/vlang/v/pull/7193

Dec 08 '20 06:12 nedpals

@JalonSolov why unpinned this issue?

Dec 27 '20 14:12 danieldaeschle

I didn't do it on purpose.

Dec 27 '20 15:12 JalonSolov

@yuyi98 unpinned it :D

Jan 04 '21 18:01 danieldaeschle

v
v copied to clipboard

Proper documentation for all vlib modules

vlib

cmd

v v copied to clipboard

Proper documentation for all vlib modules

vlib

cmd

v
v copied to clipboard