docs: Add Concepts/Modules (#971)

Adds a Modules page under concepts
documenting fx.Modules.

Also adapts a subset of our internal "writing Fx modules"
for external consumption.

docs/.vuepress/config.js

@@ -74,6 +74,7 @@ module.exports = {
         title: 'Concepts',
         children: [
           'lifecycle.md',
+          'modules.md',
         ],
       },
       {

docs/Makefile

@@ -2,7 +2,7 @@ export PATH := $(shell pwd)/bin:$(PATH)
 
 MDOX = $(shell pwd)/../bin/mdox
 MDOX_FMT_FLAGS = --soft-wraps --links.validate --links.validate.config-file $(shell pwd)/.mdox-validate.yaml
-MD_FILES = $(shell git ls-files '*.md')
+MD_FILES ?= $(shell git ls-files '*.md')
 
 .PHONY:
 fmt: $(MDOX)

docs/bin/region

@@ -2,7 +2,7 @@
 set -euo pipefail
 IFS=$'\n\t'
 
-if [[ $# -ne 2 ]]; then
+if [[ $# -lt 2 ]]; then
 	echo >&2 'USAGE: region FILE REGION1 REGION2 ...'
 	echo >&2
 	echo >&2 'Extracts text from FILE marked by "// region" blocks.'

docs/ex/modules/module.go

@@ -0,0 +1,108 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+package modules
+
+import (
+	"go.uber.org/fx"
+	"go.uber.org/zap"
+)
+
+// Module is an example of an Fx module's skeleton.
+// region start
+// region provide
+// region invoke
+// region decorate
+var Module = fx.Module("server",
+	// endregion start
+	fx.Provide(
+		New,
+		parseConfig,
+	),
+	// endregion provide
+	fx.Invoke(startServer),
+	// endregion invoke
+	fx.Decorate(wrapLogger),
+
+// region provide
+// region invoke
+)
+
+// endregion invoke
+// endregion provide
+// endregion decorate
+
+// Config is the configuration of the server.
+// region config
+type Config struct {
+	Addr string `yaml:"addr"`
+}
+
+// endregion config
+
+func parseConfig() (Config, error) {
+	return Config{}, nil
+}
+
+// Params defines the parameters of the module.
+// region params
+type Params struct {
+	fx.In
+
+	Log    *zap.Logger
+	Config Config
+}
+
+// endregion params
+
+// Result defines the results of the module.
+// region result
+type Result struct {
+	fx.Out
+
+	Server *Server
+}
+
+// endregion result
+
+// New builds a new server.
+// region new
+func New(p Params) (Result, error) {
+	// endregion new
+	return Result{
+		Server: &Server{},
+	}, nil
+}
+
+// Server is the server.
+type Server struct{}
+
+// Start starts the server.
+func (*Server) Start() error {
+	return nil
+}
+
+func startServer(srv *Server) error {
+	return srv.Start()
+}
+
+func wrapLogger(log *zap.Logger) *zap.Logger {
+	return log.With(zap.String("component", "mymodule"))
+}

docs/ex/modules/module_test.go

@@ -0,0 +1,41 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+package modules
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+	"go.uber.org/zap"
+)
+
+func TestModule(t *testing.T) {
+	var got *Server
+	app := fxtest.New(t,
+		Module,
+		fx.Supply(zap.NewNop()),
+		fx.Populate(&got),
+	)
+	app.RequireStart().RequireStop()
+	assert.NotNil(t, got)
+}