The web interface of Godoc shall document/show any Exposed method.

[sssmack]

Observe the method named Error() in the following base golang source:

https://golang.org/src/errors/errors.go

The bug is that with regard to reporting functions, the web interface of godoc shall be able to report only all exposed functions and it does not do that. The method named 'Error' is not reported and it shall be.

The godoc web interface has a feature to report all functions regardless of exposed or not and that feature does not resolve this bug. golang developers do not want or care waste time groping through many private functions when they are looking only for functions that the compiler allows them to use.

The web interface of godoc shall have the capability/feature to report only all exposed methods because a golang user needs to know about what functions are usable by them. If a golang developer does not know what functions are available and usable then they will re-write them or not use them. If the golang developer learns of this deficient behavior of the godoc web interface then they will lose confidence in godoc. They may resort to losing their development time reading golang source or out of frustration decide to not use golang.

As a side note, any exposed golang item shall have a documentation comment and errors.Error() does not.

[shantuo]

I'm not sure if I understand the issue correctly.

Observe the method named Error() in the following base golang source:

https://golang.org/src/errors/errors.go

Are you talking about a issue regarding this page? Or are you saying that the Error() method here is exported but not showing at godoc.org/errors? This issue tracker is only for the website godoc.org, not golang.org.

As why the Error() method is not showing, it is because the method belongs to an unexported errorString type which cannot be used outside the package any ways.

[sssmack]

Can we agree that functions that are usable by a golang developer shall be reported by the godoc web interface without that report also cluttering that report by showing non-usable functions?

I am talking about godoc. I am using the errors package of golang as an example of how the godoc web interface shall be reporting usable, exported functions but godoc does not do that. The example of a function that the godoc web interface does not report is named Error(). The m=all option on the URL is not acceptable as a solution because the developer does not care to also see non-usable functions.

errors.Error() is usable by a developer. Verify that for yourself by running the following program.

package main
import (
    "errors"
    "log"
)
func main() {
    e := errors.New("this is an error message.")
    log.Println(e.Error())
}

[dominikh]

errors.New is documented to return a value of type error, the built-in interface. The interface, which is linked to, is documented to contain an Error() string method.

The entire behaviour of errors.New and its return value is documented.

[sssmack]

@dominikh, I will show you how your answer does not address the bug that I have been describing.

Do this: Save the following code into your go source tree and when godoc is run as a webservice you will see no documentation about the externally declared and usable function Name() anywhere in any of the documentation. That is the bug.

I would like to see a snapshot from your browser showing godoc documentation on Name().

For anyone else reading this, please realize what started this thread:

The bug is that with regard to reporting functions, the web interface of godoc shall be able to report only all exposed functions and it does not do that.

package jimbo

// A spacy interface
type juno interface {
    Name() string
}

// New returns a reference to moon having the given name.
func New(text string) juno {
    return &moon{text}
}

// moon is a trivial.
type moon struct {
    s string
}

// Name yields the name of the moon.
func (e *moon) Name() string {
    return e.s
}

[urandom2]

gddo implements a web view compatible with the symbols exported by the go doc tool. I urge you to try your example there first and if you can get docs for your desired symbols, I think we could look into adding them here. Otherwise, I would suggest opening an issues with golang/go, as we would rather not have a different set of symbols available in either tool.

As an aside, it is generally considered bad practice to:

• Document methods that implement interfaces [0], since the interface itself already documents the method.
• Return non exported types with exported methods, as this makes interacting with types hard. You should instead use exported interfaces.

[sssmack]

I now realize that Error() is part of an interface type and that documentation for an interface function belongs at its declaration only. Documenting it again wherever it is implemented is unnecessary and confusing. In this case Error() is documentated in type error in the builtin package.