diff --git a/engine/doc.go b/engine/doc.go new file mode 100644 index 00000000..97a15163 --- /dev/null +++ b/engine/doc.go @@ -0,0 +1,21 @@ +// Mgmt +// Copyright (C) 2013-2021+ James Shubin and the project contributors +// Written by James Shubin 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 . + +// 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 diff --git a/engine/graph/engine.go b/engine/graph/engine.go index 26c3a4c2..3c6d0cca 100644 --- a/engine/graph/engine.go +++ b/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 . +// 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 ( diff --git a/engine/resources/doc.go b/engine/resources/doc.go new file mode 100644 index 00000000..06e44c88 --- /dev/null +++ b/engine/resources/doc.go @@ -0,0 +1,19 @@ +// Mgmt +// Copyright (C) 2013-2021+ James Shubin and the project contributors +// Written by James Shubin 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 . + +// Package resources contains the implementations of all the core resources. +package resources diff --git a/engine/traits/doc.go b/engine/traits/doc.go new file mode 100644 index 00000000..bf3f71f1 --- /dev/null +++ b/engine/traits/doc.go @@ -0,0 +1,20 @@ +// Mgmt +// Copyright (C) 2013-2021+ James Shubin and the project contributors +// Written by James Shubin 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 . + +// Package traits contains all the definitions and implementations of the core +// resource traits that are imported by all the resource implementations. +package traits diff --git a/engine/util/util.go b/engine/util/util.go index 02ae24ae..f1d3e445 100644 --- a/engine/util/util.go +++ b/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 . +// Package util contains utility functions that are specific to the resource +// engine. package util import ( diff --git a/lang/ast/structs.go b/lang/ast/structs.go index f1901ed2..03ca2fcd 100644 --- a/lang/ast/structs.go +++ b/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 . +// Package ast contains the structs implementing and some utility functions for +// interacting with the abstract syntax tree for the mcl language. package ast import ( diff --git a/lang/download/download.go b/lang/download/download.go index 3948ecc4..4f361127 100644 --- a/lang/download/download.go +++ b/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 . +// Package download is used for downloading language modules from git. package download import ( diff --git a/lang/gapi/gapi.go b/lang/gapi/gapi.go index 77ff2be8..108c527c 100644 --- a/lang/gapi/gapi.go +++ b/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 . +// Package gapi is the Graph API implementation for the mcl language frontend. package gapi import ( diff --git a/lang/inputs/inputs.go b/lang/inputs/inputs.go index e0594c3b..bd22cddc 100644 --- a/lang/inputs/inputs.go +++ b/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 . +// 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 ( diff --git a/lang/interfaces/doc.go b/lang/interfaces/doc.go new file mode 100644 index 00000000..8ec0bdd7 --- /dev/null +++ b/lang/interfaces/doc.go @@ -0,0 +1,20 @@ +// Mgmt +// Copyright (C) 2013-2021+ James Shubin and the project contributors +// Written by James Shubin 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 . + +// Package interfaces contains the common interfaces used in the mcl language. +// This package has the common imports that most consumers use directly. +package interfaces diff --git a/lang/interpolate/interpolate.go b/lang/interpolate/interpolate.go index 350e0946..5fb6cb41 100644 --- a/lang/interpolate/interpolate.go +++ b/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 . +// Package interpolate contains the string interpolation parser and associated +// structs and code. package interpolate import ( diff --git a/lang/interpret/interpret.go b/lang/interpret/interpret.go index d436a195..df9e0daa 100644 --- a/lang/interpret/interpret.go +++ b/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 . +// Package interpret contains the implementation of the actual interpret +// function that takes an AST and returns a resource graph. package interpret import ( diff --git a/lang/lang.go b/lang/lang.go index 0adaf6dd..39a9e29a 100644 --- a/lang/lang.go +++ b/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 . -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" diff --git a/lang/parser/lexparse.go b/lang/parser/lexparse.go index 41a2d5e5..2aa6925f 100644 --- a/lang/parser/lexparse.go +++ b/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 . +// Package parser contains the lexer and parser for the mcl language. package parser import ( diff --git a/lang/types/doc.go b/lang/types/doc.go index bbfa53f8..ba9a8cb6 100644 --- a/lang/types/doc.go +++ b/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 . -// 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 diff --git a/lang/unification/unification.go b/lang/unification/unification.go index 261ab4b1..8d6c7b56 100644 --- a/lang/unification/unification.go +++ b/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 . +// Package unification contains the code related to type unification for the mcl +// language. package unification import ( diff --git a/lang/util/util.go b/lang/util/util.go index 5aa577e1..03f5c3ec 100644 --- a/lang/util/util.go +++ b/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 . +// Package util contains utility functions that are specific to the mcl +// language. package util import ( diff --git a/langpuppet/merge.go b/langpuppet/merge.go index 645e4cd6..3942174c 100644 --- a/langpuppet/merge.go +++ b/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 . -// 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 ( diff --git a/lib/main.go b/lib/main.go index 481656b6..214bbb93 100644 --- a/lib/main.go +++ b/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 . +// 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 ( diff --git a/pgp/pgp.go b/pgp/pgp.go index fb62093b..1f84c41e 100644 --- a/pgp/pgp.go +++ b/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 . +// Package pgp contains the code related to both code and host signing and +// encryption. package pgp import ( diff --git a/test/comment_parser.go b/test/comment_parser.go index e0fcabf9..f96bf0f1 100644 --- a/test/comment_parser.go +++ b/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 . +// 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 ( diff --git a/yamlgraph/gconfig.go b/yamlgraph/gconfig.go index 9c01f210..2f79204f 100644 --- a/yamlgraph/gconfig.go +++ b/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 . -// 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 (