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.

from ghw.

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?

from ghw.

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.

from ghw.

@jaypipes So where can i help with

from ghw.

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

from ghw.

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"`
}

from ghw.

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.

from ghw.

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.

from ghw.

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

from ghw.

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]

from ghw.

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.

from ghw.

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

from ghw.

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

from ghw.

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.

from ghw.