Merge pull request #2065 from filecoin-project/docs/docgen-fixes

docgen improvements

api/api_common.go

@@ -13,11 +13,13 @@ import (
 )
 
 type Common interface {
-	// Auth
+
+	// MethodGroup: Auth
+
 	AuthVerify(ctx context.Context, token string) ([]auth.Permission, error)
 	AuthNew(ctx context.Context, perms []auth.Permission) ([]byte, error)
 
-	// network
+	// MethodGroup: Net
 
 	NetConnectedness(context.Context, peer.ID) (network.Connectedness, error)
 	NetPeers(context.Context) ([]peer.AddrInfo, error)
@@ -27,6 +29,8 @@ type Common interface {
 	NetFindPeer(context.Context, peer.ID) (peer.AddrInfo, error)
 	NetPubsubScores(context.Context) ([]PubsubScore, error)
 
+	// MethodGroup: Common
+
 	// ID returns peerID of libp2p node backing this API
 	ID(context.Context) (peer.ID, error)
 

api/api_full.go

@@ -35,26 +35,71 @@ type FullNode interface {
 	// ChainNotify returns channel with chain head updates
 	// First message is guaranteed to be of len == 1, and type == 'current'
 	ChainNotify(context.Context) (<-chan []*HeadChange, error)
+
 	// ChainHead returns the current head of the chain
 	ChainHead(context.Context) (*types.TipSet, error)
+
 	// ChainGetRandomness is used to sample the chain for randomness
 	ChainGetRandomness(ctx context.Context, tsk types.TipSetKey, personalization crypto.DomainSeparationTag, randEpoch abi.ChainEpoch, entropy []byte) (abi.Randomness, error)
+
 	// ChainGetBlock returns the block specified by the given CID
 	ChainGetBlock(context.Context, cid.Cid) (*types.BlockHeader, error)
 	ChainGetTipSet(context.Context, types.TipSetKey) (*types.TipSet, error)
-	ChainGetBlockMessages(context.Context, cid.Cid) (*BlockMessages, error)
+
-	ChainGetParentReceipts(context.Context, cid.Cid) ([]*types.MessageReceipt, error)
+	// ChainGetBlockMessages returns messages stored in the specified block
-	ChainGetParentMessages(context.Context, cid.Cid) ([]Message, error)
+	ChainGetBlockMessages(ctx context.Context, blockCid cid.Cid) (*BlockMessages, error)
+
+	// ChainGetParentReceipts returns receipts for messages in parent tipset of
+	// the specified block
+	ChainGetParentReceipts(ctx context.Context, blockCid cid.Cid) ([]*types.MessageReceipt, error)
+
+	// ChainGetParentReceipts returns messages stored in parent tipset of the
+	// specified block
+	ChainGetParentMessages(ctx context.Context, blockCid cid.Cid) ([]Message, error)
+
+	// ChainGetTipSetByHeight looks back for a tipset at the specified epoch.
+	// If there are no blocks at the specified epoch, a tipset at higher epoch
+	// will be returned
 	ChainGetTipSetByHeight(context.Context, abi.ChainEpoch, types.TipSetKey) (*types.TipSet, error)
+
+	// ChainReadObj reads ipld nodes referenced by the specified CID from chain
+	// blockstore and returns raw bytes
 	ChainReadObj(context.Context, cid.Cid) ([]byte, error)
+
+	// ChainHasObj checks if a given CID exists in the chain blockstore
 	ChainHasObj(context.Context, cid.Cid) (bool, error)
 	ChainStatObj(context.Context, cid.Cid, cid.Cid) (ObjStat, error)
+
+	// ChainSetHead forcefully sets current chain head. Use with caution
 	ChainSetHead(context.Context, types.TipSetKey) error
+
+	// ChainGetGenesis returns the genesis tipset
 	ChainGetGenesis(context.Context) (*types.TipSet, error)
+
+	// ChainTipSetWeight computes weight for the specified tipset
 	ChainTipSetWeight(context.Context, types.TipSetKey) (types.BigInt, error)
 	ChainGetNode(ctx context.Context, p string) (*IpldObject, error)
+
+	// ChainGetMessage reads a message referenced by the specified CID from the
+	// chain blockstore
 	ChainGetMessage(context.Context, cid.Cid) (*types.Message, error)
+
+	// ChainGetPath returns a set of revert/apply operations needed to get from
+	// one tipset to another, for example:
+	//```
+	//        to
+	//         ^
+	// from   tAA
+	//   ^     ^
+	// tBA    tAB
+	//  ^---*--^
+	//      ^
+	//     tRR
+	//```
+	// Would return `[revert(tBA), apply(tAB), apply(tAA)]`
 	ChainGetPath(ctx context.Context, from types.TipSetKey, to types.TipSetKey) ([]*HeadChange, error)
+
+	// ChainExport returns a stream of bytes with CAR dump of chain data
 	ChainExport(context.Context, types.TipSetKey) (<-chan []byte, error)
 
 	// MethodGroup: Sync
@@ -63,23 +108,45 @@ type FullNode interface {
 
 	// SyncState returns the current status of the lotus sync system
 	SyncState(context.Context) (*SyncState, error)
+
 	// SyncSubmitBlock can be used to submit a newly created block to the
 	// network through this node
 	SyncSubmitBlock(ctx context.Context, blk *types.BlockMsg) error
+
+	// SyncIncomingBlocks returns a channel streaming incoming, potentially not
+	// yet synced block headers.
 	SyncIncomingBlocks(ctx context.Context) (<-chan *types.BlockHeader, error)
+
+	// SyncMarkBad marks a blocks as bad, meaning that it won't ever by synced.
+	// Use with extreme caution
 	SyncMarkBad(ctx context.Context, bcid cid.Cid) error
+
+	// SyncCheckBad checks if a block was marked as bad, and if it was, returns
+	// the reason
 	SyncCheckBad(ctx context.Context, bcid cid.Cid) (string, error)
 
 	// MethodGroup: Mpool
 	// The Mpool methods are for interacting with the message pool. The message pool
 	// manages all incoming and outgoing 'messages' going over the network.
 
+	// MpoolPending returns pending mempool messages
 	MpoolPending(context.Context, types.TipSetKey) ([]*types.SignedMessage, error)
+
+	// MpoolPush pushes a signed message to mempool
 	MpoolPush(context.Context, *types.SignedMessage) (cid.Cid, error)
-	MpoolPushMessage(context.Context, *types.Message) (*types.SignedMessage, error) // get nonce, sign, push
+
+	// MpoolPushMessage atomically assigns a nonce, signs, and pushes a message
+	// to mempool
+	MpoolPushMessage(context.Context, *types.Message) (*types.SignedMessage, error)
+
+	// MpoolGetNonce gets next nonce for the specified sender.
+	// Note that this method may not be atomic. Use MpoolPushMessage instead
 	MpoolGetNonce(context.Context, address.Address) (uint64, error)
 	MpoolSub(context.Context) (<-chan MpoolUpdate, error)
-	MpoolEstimateGasPrice(context.Context, uint64, address.Address, int64, types.TipSetKey) (types.BigInt, error)
+
+	// MpoolEstimateGasPrice estimates what gas price should be used for a
+	// message to have high likelihood of inclusion in `nblocksincl` epochs
+	MpoolEstimateGasPrice(ctx context.Context, nblocksincl uint64, sender address.Address, gaslimit int64, tsk types.TipSetKey) (types.BigInt, error)
 
 	// MethodGroup: Miner
 

api/docgen/docgen.go

@@ -73,9 +73,13 @@ func init() {
 
 	addExample(bitfield.NewFromSet([]uint64{5}))
 	addExample(abi.RegisteredSealProof_StackedDrg32GiBV1)
+	addExample(abi.RegisteredPoStProof_StackedDrgWindow32GiBV1)
 	addExample(abi.ChainEpoch(10101))
 	addExample(crypto.SigTypeBLS)
 	addExample(int64(9))
+	addExample(12.3)
+	addExample(123)
+	addExample(uintptr(0))
 	addExample(abi.MethodNum(1))
 	addExample(exitcode.ExitCode(0))
 	addExample(crypto.DomainSeparationTag_ElectionProofProduction)
@@ -94,17 +98,17 @@ func init() {
 	addExample(api.PCHInbound)
 	addExample(time.Minute)
 	addExample(&types.ExecutionTrace{
-		Msg:    exampleValue(reflect.TypeOf(&types.Message{})).(*types.Message),
+		Msg:    exampleValue(reflect.TypeOf(&types.Message{}), nil).(*types.Message),
-		MsgRct: exampleValue(reflect.TypeOf(&types.MessageReceipt{})).(*types.MessageReceipt),
+		MsgRct: exampleValue(reflect.TypeOf(&types.MessageReceipt{}), nil).(*types.MessageReceipt),
 	})
 	addExample(map[string]types.Actor{
-		"t01236": exampleValue(reflect.TypeOf(types.Actor{})).(types.Actor),
+		"t01236": exampleValue(reflect.TypeOf(types.Actor{}), nil).(types.Actor),
 	})
 	addExample(map[string]api.MarketDeal{
-		"t026363": exampleValue(reflect.TypeOf(api.MarketDeal{})).(api.MarketDeal),
+		"t026363": exampleValue(reflect.TypeOf(api.MarketDeal{}), nil).(api.MarketDeal),
 	})
 	addExample(map[string]api.MarketBalance{
-		"t026363": exampleValue(reflect.TypeOf(api.MarketBalance{})).(api.MarketBalance),
+		"t026363": exampleValue(reflect.TypeOf(api.MarketBalance{}), nil).(api.MarketBalance),
 	})
 
 	maddr, err := multiaddr.NewMultiaddr("/ip4/52.36.61.156/tcp/1347/p2p/12D3KooWFETiESTf1v4PGUvtnxMAcEFMzLZbJGg4tjWfGEimYior")
@@ -117,7 +121,7 @@ func init() {
 
 }
 
-func exampleValue(t reflect.Type) interface{} {
+func exampleValue(t, parent reflect.Type) interface{} {
 	v, ok := ExampleValues[t]
 	if ok {
 		return v
@@ -126,25 +130,25 @@ func exampleValue(t reflect.Type) interface{} {
 	switch t.Kind() {
 	case reflect.Slice:
 		out := reflect.New(t).Elem()
-		reflect.Append(out, reflect.ValueOf(exampleValue(t.Elem())))
+		reflect.Append(out, reflect.ValueOf(exampleValue(t.Elem(), t)))
 		return out.Interface()
 	case reflect.Chan:
-		return exampleValue(t.Elem())
+		return exampleValue(t.Elem(), nil)
 	case reflect.Struct:
-		es := exampleStruct(t)
+		es := exampleStruct(t, parent)
 		v := reflect.ValueOf(es).Elem().Interface()
 		ExampleValues[t] = v
 		return v
 	case reflect.Array:
 		out := reflect.New(t).Elem()
 		for i := 0; i < t.Len(); i++ {
-			out.Index(i).Set(reflect.ValueOf(exampleValue(t.Elem())))
+			out.Index(i).Set(reflect.ValueOf(exampleValue(t.Elem(), t)))
 		}
 		return out.Interface()
 
 	case reflect.Ptr:
 		if t.Elem().Kind() == reflect.Struct {
-			es := exampleStruct(t.Elem())
+			es := exampleStruct(t.Elem(), t)
 			//ExampleValues[t] = es
 			return es
 		}
@@ -155,12 +159,15 @@ func exampleValue(t reflect.Type) interface{} {
 	panic(fmt.Sprintf("No example value for type: %s", t))
 }
 
-func exampleStruct(t reflect.Type) interface{} {
+func exampleStruct(t, parent reflect.Type) interface{} {
 	ns := reflect.New(t)
 	for i := 0; i < t.NumField(); i++ {
 		f := t.Field(i)
+		if f.Type == parent {
+			continue
+		}
 		if strings.Title(f.Name) == f.Name {
-			ns.Elem().Field(i).Set(reflect.ValueOf(exampleValue(f.Type)))
+			ns.Elem().Field(i).Set(reflect.ValueOf(exampleValue(f.Type, t)))
 		}
 	}
 
@@ -286,17 +293,17 @@ func main() {
 		ft := m.Func.Type()
 		for j := 2; j < ft.NumIn(); j++ {
 			inp := ft.In(j)
-			args = append(args, exampleValue(inp))
+			args = append(args, exampleValue(inp, nil))
 		}
 
-		v, err := json.Marshal(args)
+		v, err := json.MarshalIndent(args, "", "  ")
 		if err != nil {
 			panic(err)
 		}
 
-		outv := exampleValue(ft.Out(0))
+		outv := exampleValue(ft.Out(0), nil)
 
-		ov, err := json.Marshal(outv)
+		ov, err := json.MarshalIndent(outv, "", "  ")
 		if err != nil {
 			panic(err)
 		}
@@ -318,6 +325,15 @@ func main() {
 		return groupslice[i].GroupName < groupslice[j].GroupName
 	})
 
+	fmt.Printf("# Groups\n")
+
+	for _, g := range groupslice {
+		fmt.Printf("* [%s](#%s)\n", g.GroupName, g.GroupName)
+		for _, method := range g.Methods {
+			fmt.Printf("  * [%s](#%s)\n", method.Name, method.Name)
+		}
+	}
+
 	for _, g := range groupslice {
 		g := g
 		fmt.Printf("## %s\n", g.GroupName)
@@ -331,8 +347,17 @@ func main() {
 			fmt.Printf("### %s\n", m.Name)
 			fmt.Printf("%s\n\n", m.Comment)
 
+			if strings.Count(m.InputExample, "\n") > 0 {
+				fmt.Printf("Inputs:\n```json\n%s\n```\n\n", m.InputExample)
+			} else {
 				fmt.Printf("Inputs: `%s`\n\n", m.InputExample)
+			}
+
+			if strings.Count(m.ResponseExample, "\n") > 0 {
+				fmt.Printf("Response:\n```json\n%s\n```\n\n", m.ResponseExample)
+			} else {
 				fmt.Printf("Response: `%s`\n\n", m.ResponseExample)
 			}
 		}
 	}
+}