docs: Improve autogenerate godoc

There were a bunch of packages that weren't well documented. With the
recent split up of the lang package, I figured it would be more helpful
for new contributors who want to learn the structure of the project.

engine/doc.go

@@ -0,0 +1,21 @@
+// Mgmt
+// Copyright (C) 2013-2021+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+// Package engine represents the implementation of the resource engine that runs
+// the graph of resources in real-time. This package has the common imports that
+// most consumers use directly.
+package engine

engine/graph/engine.go

@@ -15,6 +15,9 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package graph contains the actual implementation of the resource graph engine
+// that runs the graph of resources in real-time. This package has the algorithm
+// that runs all the graph transitions.
 package graph
 
 import (

engine/resources/doc.go

@@ -0,0 +1,19 @@
+// Mgmt
+// Copyright (C) 2013-2021+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+// Package resources contains the implementations of all the core resources.
+package resources

engine/traits/doc.go

@@ -0,0 +1,20 @@
+// Mgmt
+// Copyright (C) 2013-2021+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+// Package traits contains all the definitions and implementations of the core
+// resource traits that are imported by all the resource implementations.
+package traits

engine/util/util.go

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package util contains utility functions that are specific to the resource
+// engine.
 package util
 
 import (

lang/ast/structs.go

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package ast contains the structs implementing and some utility functions for
+// interacting with the abstract syntax tree for the mcl language.
 package ast
 
 import (

lang/download/download.go

@@ -15,6 +15,7 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package download is used for downloading language modules from git.
 package download
 
 import (

lang/gapi/gapi.go

@@ -15,6 +15,7 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package gapi is the Graph API implementation for the mcl language frontend.
 package gapi
 
 import (

lang/inputs/inputs.go

@@ -15,6 +15,12 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package inputs contains the input parsing logic for how mcl module
+// entrypoints are handled for the language.
+//
+// In other words, given a string, does this represent stdin, a specific
+// metadata input file, a specific code file, a directory of code, some raw and
+// inline code, or nothing at all.
 package inputs
 
 import (

lang/interfaces/doc.go

@@ -0,0 +1,20 @@
+// Mgmt
+// Copyright (C) 2013-2021+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+// Package interfaces contains the common interfaces used in the mcl language.
+// This package has the common imports that most consumers use directly.
+package interfaces

lang/interpolate/interpolate.go

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package interpolate contains the string interpolation parser and associated
+// structs and code.
 package interpolate
 
 import (

lang/interpret/interpret.go

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package interpret contains the implementation of the actual interpret
+// function that takes an AST and returns a resource graph.
 package interpret
 
 import (

lang/lang.go

@@ -15,7 +15,9 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-package lang // TODO: move this into a sub package of lang/$name?
+// Package lang is the mcl language frontend that implements the reactive DSL
+// that lets users model their desired state over time.
+package lang
 
 import (
 	"bytes"

lang/parser/lexparse.go

@@ -15,6 +15,7 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package parser contains the lexer and parser for the mcl language.
 package parser
 
 import (

lang/types/doc.go

@@ -15,5 +15,5 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-// Package types provides a framework for our language values and types.
+// Package types provides a framework for our mcl language values and types.
 package types

lang/unification/unification.go

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package unification contains the code related to type unification for the mcl
+// language.
 package unification
 
 import (

lang/util/util.go

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package util contains utility functions that are specific to the mcl
+// language.
 package util
 
 import (

langpuppet/merge.go

@@ -15,7 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-// Package langpuppet implements an integration entrypoint that combines lang and Puppet.
+// Package langpuppet implements an integration entrypoint that combines lang
+// and Puppet.
 package langpuppet
 
 import (

lib/main.go

@@ -15,6 +15,9 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package lib is the home for the mgmt core library. It is implemented as a
+// library (so that it can be reused within other programs) and our cli is just
+// a wrapper around this.
 package lib
 
 import (

pgp/pgp.go

@@ -15,6 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package pgp contains the code related to both code and host signing and
+// encryption.
 package pgp
 
 import (

test/comment_parser.go

@@ -15,6 +15,9 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// XXX: consider using the https://pkg.go.dev/go/doc parser instead and also
+// checking the other fields like the package doc string.
+
 package main
 
 import (

yamlgraph/gconfig.go

@@ -15,7 +15,8 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-// Package yamlgraph provides the facilities for loading a graph from a yaml file.
+// Package yamlgraph provides the facilities for loading a graph from a yaml
+// file.
 package yamlgraph
 
 import (