"Type" is undefined in RPC documentation

[Winterhuman]

As found by a user in the Matrix room, the "Type" specified in https://docs.ipfs.tech/reference/kubo/rpc/#api-v0-dht-query is never explained; the meaning of the integer values isn't defined anywhere (or at the least it should be explained where it's stated/there should be a link back to where "Type" is defined)

[BigLep]

2022-09-02 conversation:

1. we need to look at the source code to understand this.
2. @TMoMoreau will drive this, but will need pointers from others.
3. Note that these docs are generated from Kubo. We have to make the changes there. @lidel can answer questions here.

[Winterhuman]

@lidel @TMoMoreau Any update on this? Should I move this issue to Kubo as noted by BigLep?

[ElPaisano]

@BigLep TMo and I are triaging issues. Is this dependent on Kubo?

[BigLep]

@ElPaisano : the source of truth for these docs is in ipfs/kubo. If there are errors or missing information, code changes will need to be made there. If you need more info on how ipfs/kubo feeds into ipfs/ipfs-docs, @lidel is the person to ask.

[hacdias]

This is an interesting discussion and problem. I'm not sure how easy this will be easy to fix, but I agree we should. First of all, we have to see how the response type is defined. If we look at the code, we find the definition of the response in https://github.com/ipfs/kubo/blob/5d864faac71b877ae30bd7b2f01c9dfaba68d8eb/core/commands/dht.go#L170:

 Type: routing.QueryEvent{},

Which, in turn, is defined in https://github.com/libp2p/go-libp2p/blob/97607949208fc95bea759eeaa88db3ad2c86bf38/core/routing/query.go#L35-L41:

// QueryEventType indicates the query event's type.
type QueryEventType int

// Number of events to buffer.
var QueryEventBufferSize = 16

const (
	// Sending a query to a peer.
	SendingQuery QueryEventType = iota
	// Got a response from a peer.
	PeerResponse
	// Found a "closest" peer (not currently used).
	FinalPeer
	// Got an error when querying.
	QueryError
	// Found a provider.
	Provider
	// Found a value.
	Value
	// Adding a peer to the query.
	AddingPeer
	// Dialing a peer.
	DialingPeer
)

// QueryEvent is emitted for every notable event that happens during a DHT query.
type QueryEvent struct {
	ID        peer.ID
	Type      QueryEventType
	Responses []*peer.AddrInfo
	Extra     string
}

To generate the docs for this response formats, we use some magic that relies on https://github.com/Stebalien/go-json-doc:

ipfs-docs/tools/http-api-docs/endpoints.go

Lines 159 to 169 in a026d40

	func buildResponse(res interface{}) string {
	// Commands with a nil type return text. This is a bad thing.
	if res == nil {
	return "This endpoint returns a `text/plain` response body."
	}
	desc, err := JsondocGlossary.Describe(res)
	if err != nil {
	panic(err)
	}
	return desc
	}

We will probably need to use reflection in order to be able to explain the enumerates, and change the package here: https://github.com/Stebalien/go-json-doc. That's an option and it would likely work for all the other endpoints that have missing information in the response type.

I'm not exactly sure how much work this would entail, but I hope this explanation is useful. I think a possible alternative could be to explain these types in the description of the command itself. But then the description needs to be updated every time there is a new possible value, or any is removed.

Let me know if you have any questions!

[Winterhuman]

@hacdias Is this resolved? https://docs.ipfs.tech/reference/kubo/rpc/#api-v0-dht-query still doesn't define Type in an obvious way

[hacdias]

The original question is, indeed, not solved. I'm not sure why this was closed. Maybe @ElPaisano has more info about it.

[Winterhuman]

@ElPaisano Friendly ping

[Winterhuman]

@hacdias Could this issue be reopened? It seems things have stalled, but the problem is still there

[lidel]

A potentially quickest way of handling this (than doing reflection magic) is to add ResponseDescription field which would be an optional string that, when present, is added at the end of the Response section in the RPC docs.

Wiring this up will be pretty easy, and will enable us to provide freehand text explanation of parameters that shows in both ipfs dht query --help and RPC docs.