Merge pull request #1791 from filecoin-project/feat/api-gen-2

improving the autogenerated api docs

api/api_full.go

@@ -104,9 +104,15 @@ type FullNode interface {
 
 	// Other
 
+	// MethodGroup: Client
+	// The Client methods all have to do with interacting with the storage and
+	// retrieval markets as a client
+
 	// ClientImport imports file under the specified path into filestore
 	ClientImport(ctx context.Context, ref FileRef) (cid.Cid, error)
+	// ClientStartDeal proposes a deal with a miner
 	ClientStartDeal(ctx context.Context, params *StartDealParams) (*cid.Cid, error)
+	// ClientGetDeal info returns the latest information about a given deal
 	ClientGetDealInfo(context.Context, cid.Cid) (*DealInfo, error)
 	ClientListDeals(ctx context.Context) ([]DealInfo, error)
 	ClientHasLocal(ctx context.Context, root cid.Cid) (bool, error)
@@ -124,6 +130,9 @@ type FullNode interface {
 
 	//ClientListAsks() []Ask
 
+	// MethodGroup: State
+	// The State methods are used to query, inspect, and interact with chain state
+
 	// if tipset is nil, we'll use heaviest
 	StateCall(context.Context, *types.Message, types.TipSetKey) (*InvocResult, error)
 	StateReplay(context.Context, types.TipSetKey, cid.Cid) (*InvocResult, error)
@@ -158,6 +167,10 @@ type FullNode interface {
 	StateMinerSectorCount(context.Context, address.Address, types.TipSetKey) (MinerSectors, error)
 	StateCompute(context.Context, abi.ChainEpoch, []*types.Message, types.TipSetKey) (*ComputeStateOutput, error)
 
+	// MethodGroup: Msig
+	// The Msig methods are used to interact with multisig wallets on the
+	// filecoin network
+
 	MsigGetAvailableBalance(context.Context, address.Address, types.TipSetKey) (types.BigInt, error)
 	MsigCreate(context.Context, int64, []address.Address, types.BigInt, address.Address, types.BigInt) (cid.Cid, error)
 	MsigPropose(context.Context, address.Address, address.Address, types.BigInt, address.Address, uint64, []byte) (cid.Cid, error)
@@ -167,6 +180,9 @@ type FullNode interface {
 	MarketEnsureAvailable(context.Context, address.Address, address.Address, types.BigInt) (cid.Cid, error)
 	// MarketFreeBalance
 
+	// MethodGroup: Paych
+	// The Paych methods are for interacting with and managing payment channels
+
 	PaychGet(ctx context.Context, from, to address.Address, ensureFunds types.BigInt) (*ChannelInfo, error)
 	PaychList(context.Context) ([]address.Address, error)
 	PaychStatus(context.Context, address.Address) (*PaychStatus, error)

api/docgen/docgen.go

@@ -190,7 +190,9 @@ func (v *Visitor) Visit(node ast.Node) ast.Visitor {
 	return v
 }
 
-func parseApiASTInfo() map[string]string {
+const noComment = "There are not yet any comments for this method."
+
+func parseApiASTInfo() (map[string]string, map[string]string) {
 
 	fset := token.NewFileSet()
 	pkgs, err := parser.ParseDir(fset, "./api", nil, parser.AllErrors|parser.ParseComments)
@@ -207,16 +209,33 @@ func parseApiASTInfo() map[string]string {
 	v := &Visitor{make(map[string]ast.Node)}
 	ast.Walk(v, pkgs["api"])
 
+	groupDocs := make(map[string]string)
 	out := make(map[string]string)
 	for mn, node := range v.Methods {
 		cs := cmap.Filter(node).Comments()
 		if len(cs) == 0 {
-			out[mn] = "NO COMMENTS"
+			out[mn] = noComment
 		} else {
-			out[mn] = cs[len(cs)-1].Text()
+			for _, c := range cs {
+				if strings.HasPrefix(c.Text(), "MethodGroup:") {
+					parts := strings.Split(c.Text(), "\n")
+					groupName := strings.TrimSpace(parts[0][12:])
+					comment := strings.Join(parts[1:], "\n")
+					groupDocs[groupName] = comment
+
+					break
+				}
+			}
+
+			last := cs[len(cs)-1].Text()
+			if !strings.HasPrefix(last, "MethodGroup:") {
+				out[mn] = last
+			} else {
+				out[mn] = noComment
+			}
 		}
 	}
-	return out
+	return out, groupDocs
 }
 
 type MethodGroup struct {
@@ -244,7 +263,7 @@ func methodGroupFromName(mn string) string {
 
 func main() {
 
-	comments := parseApiASTInfo()
+	comments, groupComments := parseApiASTInfo()
 
 	groups := make(map[string]*MethodGroup)
 
@@ -258,7 +277,7 @@ func main() {
 		g, ok := groups[groupName]
 		if !ok {
 			g = new(MethodGroup)
-			g.Header = groupName
+			g.Header = groupComments[groupName]
 			g.GroupName = groupName
 			groups[groupName] = g
 		}