How do we want to display linked type parameters?

[agjohnson]

Currently, with a patched sphinx domain, the display looks like such on the go support branch:

This is the traditional output for documenting parameters in sphinx, however sphinx expects parameter listing with a description. Parameter types could be listed inline in the signature as well though, with some modifications to the sphinx golang domain, but this is a pattern that deviates slightly from traditional parameter listing.

The other option is to expect some form of parameter description in the member documentation markup.

[swenson]

AFAIK, Go does not have a standard way to document parameters.

But... that is also an opportunity. We could define our own way of doing it, and document it.

Maybe do something javay, with @param input something something

[optimality]

If we're not doing parameter docs, then I think most go programmers will
expect to see the types in the signature ("func And(u1, u2 UUID) UUID").

On Sun, May 31, 2015 at 11:10 AM, Christopher Swenson <
notifications@github.com> wrote:

AFAIK, Go does not have a standard way to document parameters.

But... that is also an opportunity. We could define our own way of doing
it, and document it.

Maybe do something javay, with @param input something something

—
Reply to this email directly or view it on GitHub
#4 (comment).

[agjohnson]

Played around with this a bit more yesterday, a mix of the two seems to work. That is, using the sphinx domain to link inline types (not working quite yet due to a bug in the sphinx golang domain) and outputting the sphinx directives that describe parameter type. This won't show the explicit parameter list until the developer added the param directive to the function documentation.

ie, by default the output of:

// This is the documentation for foo
func foo(bar interface{}) string {
    ...
}

will be:

.. go:func:: foo(bar interface{})
    This is the documentation for foo

    :type bar: interface{}
    :returntype string:

The above won't show the explicit parameter list, as param needs to be defined. Once the developer adds that, ie:

// This is the documentation for foo
// 
// :param bar: Something to pass in
func foo(bar interface{}) string {
    ...
}

the output of sphinx will then be:

.. go:func:: foo(bar interface{})
    This is the documentation for foo

    :param bar: Something to pass in

    :type bar: interface{}
    :returntype string:

This should remain fairly flexible.

[AWhetter]

Closing this now that we are dropping support for documenting languages other than Python. See #248 for more information on this decision.