GoDoc strings

[icholy]

Since the documentation is separate from the source, the standard tooling can't leverage it (godoc, gocode, sourcegraph, etc...). Is there a reason the docs are not in the source?

[jaypipes]

Hi @icholy! No reason other than my lack of familiarity with the Go documentation tooling. Would love some assistance on this if you're interested in helping out?

I like having lots of good documentation in the README.md file, so I wouldn't want to get rid of that. But certainly I'd also like to align source code documentation with the Go tooling needs.

[glvr182]

I see you added the help wanted label, and I would love to help out in this repo. What part of the documentation would you like help with?

[jaypipes]

Hi @glvr182! Basically, this is about making ghw's documentation follow Golang standards, which unfortunately I haven't had a chance to read up on those standards and make any necessary changes to.

[glvr182]

@jaypipes So where can i help with

[jaypipes]

@glvr182

Read https://blog.golang.org/godoc-documenting-go-code and then go from there.

1) I believe we need to have a doc.go file that contains much of the long-form documentation currently in the README.md file.

2) Running godoc . in the checked-out source directory yields a wide variety of things, not all of which seem to be well-organized and there are definitely structs and functions that do not have in-code comments that are read by godoc to generate that output.

3) Figure out how to generate HTML documentation for the source code itself. I've read the godoc program's help output and it's less than helpful... need to research how to do this...

[icholy]

Most of the work is just taking the struct documentation and moving it into the source.

Memory

Information about the host computer's memory can be retrieved using the ghw.Memory() function which returns a pointer to a ghw.MemoryInfo struct.

The ghw.MemoryInfo struct contains three fields:

• ghw.MemoryInfo.TotalPhysicalBytes contains the amount of physical memory on the host
• ghw.MemoryInfo.TotalUsableBytes contains the amount of memory the system can actually use. Usable memory accounts for things like the kernel's resident memory size and some reserved system bits
• ghw.MemoryInfo.SupportedPageSizes is an array of integers representing the size, in bytes, of memory pages the system supports

// MemoryInfo contains information about the host computer's memory.
type MemoryInfo struct {
    // TotalPhysicalBytes contains the amount of physical memory on the host
    TotalPhysicalBytes int64 `json:"total_physical_bytes"`

    // TotalUsableBytes contains the amount of memory the system can actually use.
    // Usable memory accounts for things like the kernel's resident memory size and
    // some reserved system bits
    TotalUsableBytes int64 `json:"total_usable_bytes"`

    // SupportedPageSizes is an array of integers representing the size, in bytes,
    // of memory pages the system supports
    SupportedPageSizes []uint64 `json:"supported_page_sizes"`
}

[jaypipes]

The issue with that is that I still want the README.md to have well-written long-form documentation and not have areas where I need to worry about content in the README getting out of sync with content in code comments in the Go source code. If there was a way to generate good looking markdown from the Go source code, I'd certainly be interested in investigating that path.

[jpo-joyent]

I think this is why many projects just link to https://godoc.org/github.com/jaypipes/ghw from their README.

If you really prefer it duplicated inline in the README as checked into the repo though, https://github.com/robertkrimen/godocdown (which I've just found and never tried) seems like a rather promising option.

[jaypipes]

Yeah, I was looking at that earlier. I think it's worth checking into...

[icholy]

I think that the README should contain the following. The rest can live in the Godoc.

ghw - Golang HardWare discovery/inspection library

ghw is a small Golang library providing hardware inspection and discovery.

Design Principles

• No root privileges needed for discovery

  ghw goes the extra mile to be useful without root priveleges. We query for host hardware information as directly as possible without relying on shellouts to programs like dmidecode that require root privileges to execute.

• Well-documented code and plenty of example code

  The code itself should be well-documented, of course, with lots of usage examples.

• Interfaces should be consistent across modules

  Each module in the library should be structured in a consistent fashion, and the structs returned by various library functions should have consistent attribute and method names.

Overriding the root mountpoint ghw uses

The default root mountpoint that ghw uses when looking for information about the host system is /. So, for example, when looking up CPU information on a Linux system, ghw.CPU() will use the path /proc/cpuinfo.

If you are calling ghw from a system that has an alternate root mountpoint, you can either set the GHW_CHROOT environment variable to that alternate path, or call the module constructor function with the ghw.WithChroot() modifier.

For example, if you are executing from within an application container that has bind-mounted the root host filesystem to the mount point /host, you would set GHW_CHROOT to /host so that ghw can find /proc/cpuinfo at /host/proc/cpuinfo.

Alternately, you can use the ghw.WithChroot() function like so:

cpu, err := ghw.CPU(ghw.WithChroot("/host"))

Disabling warning messages

When ghw isn't able to retrieve some information, it may print certain warning messages to stderr. To disable these warnings, simply set the GHW_DISABLE_WARNINGS environs variable:

$ ghwc memory
WARNING:
Could not determine total physical bytes of memory. This may
be due to the host being a virtual machine or container with no
/var/log/syslog file, or the current user may not have necessary
privileges to read the syslog. We are falling back to setting the
total physical amount of memory to the total usable amount of memory
memory (24GB physical, 24GB usable)

$ GHW_DISABLE_WARNINGS=1 ghwc memory
memory (24GB physical, 24GB usable)

Serialization

All of the ghw XXXInfo structs -- e.g. ghw.CPUInfo -- have two methods for producing a serialized JSON or YAML string representation of the contained information:

• JSONString() returns a string containing the information serialized into JSON. It accepts a single boolean parameter indicating whether to use indentation when outputting the string
• YAMLString() returns a string containing the information serialized into YAML

Developers

Contributions to ghw are welcomed! Fork the repo on GitHub and submit a pull request with your proposed changes. Or, feel free to log an issue for a feature request or bug report.

This project uses dep to manage dependencies. Dependencies must be set to a specific tag (no open-ended dependencies) in the Gopkg.toml file. To manually execute dep run make dep.

Running tests

You can run unit tests easily using the make test command, like so:

[jaypipes@uberbox ghw]$ make test
go test github.com/jaypipes/ghw github.com/jaypipes/ghw/cmd/ghwc
ok      github.com/jaypipes/ghw 0.084s
?       github.com/jaypipes/ghw/cmd/ghwc    [no test files]

[glvr182]

I think the godoc should be used for the code information. Because as stated above, many projects use it, and it is completly free (if it is hosted on github). As for the information that does not concern the code, that could be inside the readme. As @icholy stated.

[jaypipes]

ack, @glvr182 and @icholy, that's fair.

Glenn, please feel free to work on a set of patches that would do just that! :)

Thank you very much in advance! -jay

[jaypipes]

@glvr182 @icholy @jpo-joyent OK, so I put together a doc.go and updated the cpu.go module to have in-code comments/descriptions for all struct fields, member methods and package-level functions.

If you go to https://godoc.org/github.com/jaypipes/ghw you will see what the new long-form docs look like.

If you ask me, I think they look terrible compared to the existing README.md markdown docs and are harder to read and understand. I'm interested in your thoughts and opinions. Please share.

[icholy]

If you're going to include the examples in the godoc, there's built-in support for it https://blog.golang.org/examples

I prefer keeping the long-form docs in the README though.