How to read package documentation

user_12990688 0
Viewed 641

I am trying to understand how to use/call libraries & functions of Golang by reading the official documentation but couldn't fully comprehend.

Below are some examples that I hope to get advise from the experts here in SO

Example 1: time

From the documentation:

type Time
  func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time
  func Now() Time

I interpret the above as type Time has method Now which does not take in any input and returns a Time type.

thus, 

var t time.Time
fmt.Println(t)

yields 0001-01-01 00:00:00 +0000 UTC So. t is a valid time.Time type variable.

Question 1:
But why is t.Now() throwing an error t.Now undefined (type time.Time has no field or method Now)?

Question 2:
Interestingly, time.Now() returns the value desired. Does that mean Now() is not a method of type Time?

go
2 Answers

var t time.Time declares a variable of type time.Time with the zero value for the type.

func Now() Time: Now() is a function with no parameters which returns type time.Time

func (t Time) Month() Month: Month() is a method on the receiver t type time.Time with no parameters which returns type time.Month.

For example,

package main

import (
    "fmt"
    "time"
)

func main() {
    var t time.Time
    fmt.Println(t)
    t = time.Now()
    fmt.Println(t)
    m := t.Month()
    fmt.Println(m)
}

Playground: https://play.golang.org/p/Ume5kxDAe05

Output:

0001-01-01 00:00:00 +0000 UTC
2009-11-10 23:00:00 +0000 UTC m=+0.000000001
November

Note: In the playground the time begins at 2009-11-10 23:00:00 UTC. This makes it easier to cache programs by giving them deterministic output.

Take A Tour of Go.

See The Go Programming Language Specification

user_2217000

I think what you are really asking here is: why is the package documentation laid out the way it is? That is, for this specific case, in this specific package documentation, we see:

type Time
  func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time
  func Now() Time

where the type Time line appears by itself, then immediately underneath it, several func declarations appear that return a value of type Time.

The reason these are indented two characters is to indicate that these functions return a value of type Time. The reason that they appear under the type Time line is that these functions return a value of type Time.

In this case, both reasons add up to the same thing—they're redundant. That's OK though! It's just a function of the fact that the Go documentation generator is a program that obeys these sort and indent rules. Nothing here implies that the two functions are receiver functions.

Consider another example from the same package documentation. Somewhat earlier, we see:

type Duration
    func ParseDuration(s string) (Duration, error)
    func Since(t Time) Duration
    func Until(t Time) Duration

Here, this tells us that all three of these functions return a Duration—though the first one returns both a Duration and an error. The ParseDuration function is an ordinary function. It is the functions Since and Until that are receiver functions.1 They take a receiver argument of type Time (and no other arguments) and return a value of type Duration.

In some other design, it might make sense to sort the Since and Until functions underneath the type name Time, since these are receiver functions of type Time. But the package documentation sorts (and groups) by return type, not receiver or argument type. That's all there really is to it here.

1You can—and the spec does—call these methods if you like.

user_12564520
Related