Vlang tutorials — docs

Hi everyone, welcome to the third episode in this series where I share quick tips on how to use a feature of vlang.

The main reason for the existence of this series is to document solutions that I struggled with in the past, not just for the future me but for everyone else, and today's tutorial will be on making v doc work by generating documentation for our modules in an HTML-friendly way.

As the name suggests, V doc is a feature to add documentation to our module and export it, and its usage basically consists of first:

Creating a module

To create a module we need to create a folder with the name of the module, for now, let's call it “mymodule”.

mkdir mymodule

Then we go into the folder and create a v file, for example, “example.v”

Inside “example.v” we can add two functions:

module mymodule

pub fn my_func() {
 println('this is a function')
}

pub fn sum(v int, f int) int {
 return v+f
}

We added two functions that we want to add documentation about its usage and what it does, and to do it we have to add comments in the top of each function like this:

module mymodule

// my_func this is a function that prints "this is a function",
// super cool right?!
// pub
pub fn my_func() {
 println('this is a function')
}

// This function receives two integers and return the sum of them.
// when the docs are generated notice by how "." breaks the line, 
// and how a "," is interpreted as a one liner description
pub fn sum(v int, f int) int {
 return v+f
}

Now that we properly added descriptions to our functions, we have to generate the documentation

v doc -m -f html ./mymodule

-m for specifying a specific module(“mymodule”) and -f to determine the format file that will be an HTML.

Now in our “mymodule” folder should be another folder called _docs, inside “_docs” folder there's a “mymodule.html” file, that when opened in the browser should show something like this:

v docs UI

Or if dark mode is preferred:

V docs dark mode

And as Dora would say:

We did it !! Yeah we did it!!

And this is how we can generate documentation automatically with V, thanks for reading, and hope it was useful for you.

Have a nice day! Happy coding!