doc: Add FAQ page

docs/.vuepress/config.js

@@ -106,6 +106,7 @@ module.exports = {
           'modules.md',
         ],
       },
+      ['faq.md', 'FAQ'],
       {
         title: 'Community',
         children: [

docs/faq.md

@@ -0,0 +1,47 @@
+# Frequently Asked Questions
+
+This page contains answers to common questions and issues with using Fx.
+
+## Does the order of `fx.Option`s matter?
+
+No, the order in which you provide various Fx options
+to `fx.Options`, `fx.New`, `fx.Module`, and others does not matter.
+
+Ordering is determined by dependencies,
+and dependencies are determined by function parameters and return types.
+
+If `ParseConfig` returns a `*Config`,
+and `NewLogger` accepts a `*Config` parameter,
+then `ParseConfig` will always run before `NewLogger`.
+
+The following are all equivalent:
+
+```go
+fx.Options(fx.Provide(ParseConfig, NewLogger))
+fx.Options(fx.Provide(NewLogger, ParseConfig))
+fx.Options(fx.Provide(ParseConfig), fx.Provide(NewLogger))
+fx.Options(fx.Provide(NewLogger), fx.Provide(ParseConfig))
+```
+
+## Why does `fx.Supply` not accept interfaces?
+
+This is a technical limitation of how reflection in Go works.
+Suppose you have:
+
+```go
+var redisClient ClientInterface = &redis.Client{ ... }
+```
+
+When you call `fx.Supply(redisClient)`,
+the knowledge that you intended to use this as a `ClientInterface` is lost.
+Fx has to use runtime reflection to inspect the type of the value,
+and at that point the Go runtime only tells it that it’s a `*redis.Client`.
+
+You can work around this with the `fx.Annotate` function
+and the `fx.As` annotation.
+
+```go
+fx.Supply(
+  fx.Annotate(redisClient, fx.As(new(ClientInterface))),
+)
+```

supply_test.go

@@ -21,7 +21,9 @@
 package fx_test
 
 import (
+	"bytes"
 	"errors"
+	"io"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -110,6 +112,25 @@ func TestSupply(t *testing.T) {
 		require.Same(t, thirdIn, out.Third)
 	})
 
+	t.Run("AnnotateIsSupported", func(t *testing.T) {
+		t.Parallel()
+
+		var out struct {
+			fx.In
+
+			Got io.Writer
+		}
+
+		var give bytes.Buffer
+		app := fxtest.New(t,
+			fx.Supply(fx.Annotate(&give, fx.As(new(io.Writer)))),
+			fx.Populate(&out),
+		)
+		defer app.RequireStart().RequireStop()
+
+		require.Same(t, &give, out.Got)
+	})
+
 	t.Run("InvalidArgumentIsSupplied", func(t *testing.T) {
 		t.Parallel()