Merge pull request #3262 from filecoin-project/feat/apidocgen

Wire up API doc generator

.circleci/config.yml

@@ -252,6 +252,27 @@ jobs:
       - run:
           command: "! go fmt ./... 2>&1 | read"
 
+  cbor-gen-check:
+    executor: golang
+    steps:
+      - install-deps
+      - prepare
+      - run: make deps
+      - run: go install golang.org/x/tools/cmd/goimports
+      - run: go install github.com/hannahhoward/cbor-gen-for
+      - run: go generate ./...
+      - run: git --no-pager diff
+      - run: git --no-pager diff --quiet
+
+  docs-check:
+    executor: golang
+    steps:
+      - install-deps
+      - prepare
+      - run: make docsgen
+      - run: git --no-pager diff
+      - run: git --no-pager diff --quiet
+
   lint: &lint
     description: |
       Run golangci-lint.
@@ -319,6 +340,8 @@ workflows:
       - lint-all
       - mod-tidy-check
       - gofmt
+      - cbor-gen-check
+      - docs-check
       - test:
           codecov-upload: true
           test-suite-name: full

Makefile

@@ -279,5 +279,8 @@ method-gen:
 
 gen: type-gen method-gen
 
+docsgen:
+	go run ./api/docgen > documentation/en/api-methods.md
+
 print-%:
 	@echo $*=$($*)

api/docgen/docgen.go

@@ -12,22 +12,29 @@ import (
 	"time"
 	"unicode"
 
+	"github.com/ipfs/go-cid"
+	"github.com/ipfs/go-filestore"
+	"github.com/libp2p/go-libp2p-core/network"
+	"github.com/libp2p/go-libp2p-core/peer"
+	pubsub "github.com/libp2p/go-libp2p-pubsub"
+	"github.com/multiformats/go-multiaddr"
+
 	"github.com/filecoin-project/go-address"
 	"github.com/filecoin-project/go-bitfield"
+	datatransfer "github.com/filecoin-project/go-data-transfer"
+	"github.com/filecoin-project/go-fil-markets/retrievalmarket"
 	"github.com/filecoin-project/go-jsonrpc/auth"
+	"github.com/filecoin-project/go-multistore"
+
+	"github.com/filecoin-project/specs-actors/actors/abi"
+	"github.com/filecoin-project/specs-actors/actors/crypto"
+	"github.com/filecoin-project/specs-actors/actors/runtime/exitcode"
+
 	"github.com/filecoin-project/lotus/api"
 	"github.com/filecoin-project/lotus/api/apistruct"
 	"github.com/filecoin-project/lotus/build"
 	"github.com/filecoin-project/lotus/chain/types"
 	"github.com/filecoin-project/lotus/node/modules/dtypes"
-	"github.com/filecoin-project/specs-actors/actors/abi"
-	"github.com/filecoin-project/specs-actors/actors/crypto"
-	"github.com/filecoin-project/specs-actors/actors/runtime/exitcode"
-	"github.com/ipfs/go-cid"
-	"github.com/ipfs/go-filestore"
-	"github.com/libp2p/go-libp2p-core/network"
-	"github.com/libp2p/go-libp2p-core/peer"
-	"github.com/multiformats/go-multiaddr"
 )
 
 var ExampleValues = map[reflect.Type]interface{}{
@@ -71,6 +78,7 @@ func init() {
 		panic(err)
 	}
 	addExample(pid)
+	addExample(&pid)
 
 	addExample(bitfield.NewFromSet([]uint64{5}))
 	addExample(abi.RegisteredSealProof_StackedDrg32GiBV1)
@@ -98,6 +106,12 @@ func init() {
 	addExample(build.APIVersion)
 	addExample(api.PCHInbound)
 	addExample(time.Minute)
+	addExample(datatransfer.TransferID(3))
+	addExample(datatransfer.Ongoing)
+	addExample(multistore.StoreID(50))
+	addExample(retrievalmarket.ClientEventDealAccepted)
+	addExample(retrievalmarket.DealStatusNew)
+	addExample(network.ReachabilityPublic)
 	addExample(&types.ExecutionTrace{
 		Msg:    exampleValue(reflect.TypeOf(&types.Message{}), nil).(*types.Message),
 		MsgRct: exampleValue(reflect.TypeOf(&types.MessageReceipt{}), nil).(*types.MessageReceipt),
@@ -111,6 +125,14 @@ func init() {
 	addExample(map[string]api.MarketBalance{
 		"t026363": exampleValue(reflect.TypeOf(api.MarketBalance{}), nil).(api.MarketBalance),
 	})
+	addExample(map[string]*pubsub.TopicScoreSnapshot{
+		"/blocks": {
+			TimeInMesh:               time.Minute,
+			FirstMessageDeliveries:   122,
+			MeshMessageDeliveries:    1234,
+			InvalidMessageDeliveries: 3,
+		},
+	})
 
 	maddr, err := multiaddr.NewMultiaddr("/ip4/52.36.61.156/tcp/1347/p2p/12D3KooWFETiESTf1v4PGUvtnxMAcEFMzLZbJGg4tjWfGEimYior")
 	if err != nil {

chain/gen/genesis/miners.go

@@ -330,13 +330,13 @@ type fakeRand struct{}
 
 func (fr *fakeRand) GetChainRandomness(ctx context.Context, personalization crypto.DomainSeparationTag, randEpoch abi.ChainEpoch, entropy []byte) ([]byte, error) {
 	out := make([]byte, 32)
-	_, _ = rand.New(rand.NewSource(int64(randEpoch * 1000))).Read(out)
+	_, _ = rand.New(rand.NewSource(int64(randEpoch * 1000))).Read(out) //nolint
 	return out, nil
 }
 
 func (fr *fakeRand) GetBeaconRandomness(ctx context.Context, personalization crypto.DomainSeparationTag, randEpoch abi.ChainEpoch, entropy []byte) ([]byte, error) {
 	out := make([]byte, 32)
-	_, _ = rand.New(rand.NewSource(int64(randEpoch))).Read(out)
+	_, _ = rand.New(rand.NewSource(int64(randEpoch))).Read(out) //nolint
 	return out, nil
 }
 

chain/validation/keymanager.go

@@ -70,7 +70,7 @@ func (k *KeyManager) Sign(addr address.Address, data []byte) (acrypto.Signature,
 }
 
 func (k *KeyManager) newSecp256k1Key() *wallet.Key {
-	randSrc := rand.New(rand.NewSource(k.secpSeed))
+	randSrc := rand.New(rand.NewSource(k.secpSeed)) // nolint
 	prv, err := crypto.GenerateKeyFromSeed(randSrc)
 	if err != nil {
 		panic(err)

cli/mpool.go

@@ -106,7 +106,7 @@ var mpoolClear = &cli.Command{
 
 		really := cctx.Bool("really-do-it")
 		if !really {
-			return fmt.Errorf("--really-do-it must be specified for this action to have an effect; you have been warned.")
+			return fmt.Errorf("the --really-do-it flag must be specified for this action to have an effect; you have been warned")
 		}
 
 		local := cctx.Bool("local")

documentation/en/.library.json

@@ -175,6 +175,12 @@
           "github": "en/api-scripting-support.md",
           "value": null
         },
+        {
+          "title": "API Methods",
+          "slug": "en+api-methods",
+          "github": "en/api-methods.md",
+          "value": null
+        },
         {
           "title": "API Troubleshooting",
           "slug": "en+api-troubleshooting",