V: Module Documentation Urgently Needed

[madranet]

V version:
v --version
V 0.1.25 6574420

OS:
OSX 10,14,14

What did you do?
ran v doc with various modules listed on the Modules page

What did you expect to see?
Some form of usable documentation generated

What did you see instead?
A lot of times, various error messages. When documentation is generated –how is it supposed to be accessed?

---

As it says on the Modules documentation page at the moment:

This page is work in progress, none of the links work.

For now you can generate module docs locally:

v doc os
v doc http

Unfortunately, in a lot of cases this doesn't actually work. For example trying to build docs for something as fundamental as the os module, results in the following error:

```
Building module "os" (dir="vlib/os")...

Generating a V header file for module vlib/os
/Users/madra/v/vlib/os
next token = main
vlib/os/bare/bare_example_linux.v:1:6: syntax error: unexpected fn, expecting module
1| fn main() {
^
2| sys_write(1, 'hellon'.str, 6)
3| s := 'test stringn'
// vlib/os module header

module os
````

It's a similar story with many of the other modules.

This post would be eleventy billion miles long if I posted the entirety of the all the error output generated when running v doc against the various modules listed on the Modules page [especially the ones which panic]. But they can be grouped into a few similar kinds.

So, of all the modules listed on the Modules page, trying v doc <module> produces the following:

Three fail with a V panic: idx error [or similar]:

• v doc benchmark
• v doc compiler
• v doc gg

Two fail with an error No input .v files \ V panic: failed to open file error [or similar]:

• v doc encoding
• v doc ui

[Running v install in case the error was caused by those modules not being installed doesn't work. That produces errors too]:

````
v install encoding
Skipping module "encoding", since it is missing name or url information.

v install ui
Updating module "ui"...
Failed updating module "ui".
````

Three module docs fail to build with a syntax error:

• v doc crypto

````
Building module "crypto" (dir="vlib/crypto")...

Generating a V header file for module vlib/crypto
/Users/madra/v/vlib/crypto
vlib/crypto/rc4/rc4.v:19:6: module crypto.internal.subtle can only be imported internally by libs
17|
18| // A Cipher is an instance of RC4 using a particular key.
19| struct Cipher {
^
20| mut:
21| s []u32
// vlib/crypto module header

module crypto
````

• v doc os
  ``` Building module "os" (dir="vlib/os")... Generating a V header file for modulevlib/os /Users/madra/v/vlib/os next token =main vlib/os/bare/bare_example_linux.v:1:6: syntax error: unexpectedfn, expectingmodule`
  1| fn main() {
  ^
  2| sys_write(1, 'hellon'.str, 6)
  3| s := 'test stringn'
  // vlib/os module header

module os
````

• v doc time

``` Building module "time" (dir="vlib/time")... Generating a V header file for modulevlib/time /Users/madra/v/vlib/time next token =) vlib/time/misc/misc.v:7:29: syntax error: unexpected(, expecting)`
5|
6| const (
7| start_time_unix = time.now().unix
^
8| )
9| // random returns a random time struct in the past.
// vlib/time module header

module time
````

The following five module documentations build, in the sense that they don't bomb out and they do produce output*:

• v doc gl
• v doc gx
• v doc json
• v doc math
• v doc rand

However that output seems to be little more than a list of functions that module contains. For example, here's a snippet from the [very long] output of v doc math:

fn hypot (a, b f64) f64 fn lcm (a, b i64) i64 fn log (a f64) f64 fn log2 (a f64) f64 fn log10 (a f64) f64 fn log_gamma (a f64) f64 fn log_n (a, b f64) f64 fn max (a, b f64) f64 fn min (a, b f64) f64 fn pow (a, b f64) f64 fn radians (degrees f64) f64 fn round (f f64) f64 fn sin (a f64) f64 fn sinh (a f64) f64 fn sqrt (a f64) f64 fn tan (a f64) f64 fn tanh (a f64) f64 fn trunc (a f64) f64 fn aprox_sin (a f64) f64 fn aprox_cos (a f64) f64 fn complex (re f64, im f64) Complex fn (c Complex) str () string fn (c Complex) abs () f64 fn (c Complex) mod () f64 fn (c Complex) angle () f64 fn (c1 Complex) + (c2 Complex) Complex fn (c1 Complex) - (c2 Complex) Complex fn (c1 Complex) * (c2 Complex) Complex fn (c1 Complex) / (c2 Complex) Complex fn (c1 Complex) add (c2 Complex) Complex fn (c1 Complex) subtract (c2 Complex) Complex fn (c1 Complex) multiply (c2 Complex) Complex fn (c1 Complex) divide (c2 Complex) Complex fn (c Complex) conjugate () Complex fn (c Complex) addinv () Complex fn (c Complex) mulinv () Complex fn (c Complex) pow (n f64) Complex fn (c Complex) root (n f64) Complex

*_[with the exception of json which doesn't crash but doesn't produce any output either, apart from the module name]_

There's no information about how any of this should be used and the 'help' documentation that's supposedly been built doesn't seem to be accessible in any way.

I thought maybe after the documentation had been built, I would be able to access it using something like v help <modulename> or v help module <modulename> but both of those just print out the same info as plain 'ol v help

Frankly, I'm at a bit of a loss here. I really want to get stuck into playing with V but there just seems to be a black hole where most of the documentation [beyond the basic syntax outline on the Docs page] should be.

I'm actually picking my way blindly through at the minute by reading the Go docs, applying the same code in V and hoping it either works, or I get an error message which is helpful enough to point me in the right direction.

Which is a pretty ridiculous state of affairs!

[madranet]

Sorry for the Bug. I only got the options to tag this as a Bug or Feature Request. I don't know how to change it or define a new tag.

[spytheman]

@madranet , for now you best bet is to read the actual source code itself.
v doc does not work as it should right now, as you have already noticed yourself.
¯_(ツ)_/¯

[leahlundqvist]

The website redesign I’m working on automatically updates itself from the docs readme so it should be a lot easier to keep it up to date

[dhonx]

@madranet https://github.com/vlang/v/blob/master/doc/docs.md

[madranet]

@madranet https://github.com/vlang/v/blob/master/doc/docs.md

Cheers. That's good for keeping abreast of the latest version of the Documentation page. But, as I said up there ^^ that only gets you as far as understanding the basic syntax. Once you start wanting to actually do 'stuff' you're pretty much going to need to know at least what's available in the builtin module and, most likely the os module too. Even if, for now, there was only documentation available for those two, it would help a lot.

As @spytheman points out; at the minute it's a case of reading the source code or [as I've been doing] trying things from Go and hoping V has something sufficiently similar that the compiler might throw me a helpful did you mean...? error.

EDIT: Sorry. My bad. After looking at the source for the builtin module I can see that it deals with the "builtin" types [Duh!]. I'd pre-assumed builtin was V's term for what might be called the stdlib

[medvednikov]

vdoc will work this month after the new parser is finished, all module docs will be generated.

[jm-duro]

My sheet is far from finished but it can already help to generate a temporary help file or to find duplicate code. See http://jean-marc.duro.pagesperso-orange.fr/public.ods.

[serkonda7]

Can be closed I think.

[JalonSolov]

Agreed. vdoc works rather well, these days, and is used to generate https://modules.vlang.io/, which is now linked from the home page.