x/tools/cmd/godoc: show internal packages when explicitly requested

[jacobsa]

godoc's HTTP viewer by default appears to hide internal/ directories. For example, neither of these views give a hint that net/internal/socktest exists:

• /pkg/
• /pkg/net/

But sometimes it's nice to be able to look at the internals of a package that you're working on. (In particular, if there are a few internal packages, it's nice to see a list.) However, godoc continues to deny the existence of net/internal/ even when it's explicitly requested:

• /pkg/net/internal/

Instead you must already know exactly what you're looking for to be able to see it.

Can/should godoc be changed to show internal packages when an internal directory is explicitly requested, as in the /pkg/net/internal/ case above?

[adg]

You can see them with http://tip.golang.org/pkg/?m=all

I think it makes sense to hide these on golang.org, but probably not for most general godoc instances.

It was issue #8879 that had them removed.

[jacobsa]

Thanks for the tip, that's great to know. It's not very discoverable though, so it would be nice if it were automatic when I've explicitly navigated to an internal/ directory. And yes, maybe good to make it the default outside of golang.org.

[perillo]

What about adding a flag for setting the default PageInfoMode?

As an example:

diff --git a/cmd/godoc/main.go b/cmd/godoc/main.go
index 48a658e0..a1350596 100644
--- a/cmd/godoc/main.go
+++ b/cmd/godoc/main.go
@@ -290,6 +290,7 @@ func main() {
    pres.ShowTimestamps = *showTimestamps
    pres.ShowPlayground = *showPlayground
    pres.DeclLinks = *declLinks
+   pres.Mode = godoc.NoFiltering
    if *notesRx != "" {
        pres.NotesRx = regexp.MustCompile(*notesRx)
    }
diff --git a/godoc/pres.go b/godoc/pres.go
index 1daa5a12..3a7f4490 100644
--- a/godoc/pres.go
+++ b/godoc/pres.go
@@ -46,6 +46,7 @@ type Presentation struct {
    ShowTimestamps bool
    ShowPlayground bool
    DeclLinks      bool
+   Mode           PageInfoMode

    // NotesRx optionally specifies a regexp to match
    // notes to render in the output.
diff --git a/godoc/server.go b/godoc/server.go
index 17514418..bbeef2b3 100644
--- a/godoc/server.go
+++ b/godoc/server.go
@@ -395,6 +395,10 @@ func (m PageInfoMode) names() []string {
 // URL form value "m". It is value is a comma-separated list of mode names
 // as defined by modeNames (e.g.: m=src,text).
 func (p *Presentation) GetPageInfoMode(r *http.Request) PageInfoMode {
+   if p.Mode != 0 {
+       return p.Mode
+   }
+
    var mode PageInfoMode
    for _, k := range strings.Split(r.FormValue(PageInfoModeQueryString), ",") {
        if m, found := modeNames[strings.TrimSpace(k)]; found {

[akavel]

@rsc would there be a chance this is revisited? I just had a team member complain that it makes development of internal packages annoying and unfriendly, making them hesitant whether they should even use an internal directory at all; and I seen it only fair to agree with them that it's a PITA. Please remember that newbies are the only ones that can tell us "the emperor has no clothes", as we're already so used to it that we don't notice the papercuts anymore, and we already grew weird reflexes to overcome them.

[nhooyr]

?m=all also shows unexported symbols which can make the godoc for a large package quite verbose.

[tonglil]

What I'd like to see is ?m=internal to show exported internal packages.

This is what I'd like to look at when developing my own app internally, ie with my team, where we care about and use the exported types, but not beyond that.

For example, if someone else on my team writes an internal exported type that I use in another package or test, I'd like to see the GoDocs, but not I don't need to see the unexported helpers.

[jpap]

I like the idea of ?m=internal, though it the UX would be a better still if it were a toggle button on the generated webpage itself.

I would also be happy to see it enabled via the command-line, as an -internal flag on x/tools/cmd/godoc. There already seem to be flags for enabling/disabling features like -index and -links.

This issue is almost 5 years old now... how to move it forward given the number of 👍 here?

[gopherbot]

Change https://golang.org/cl/337149 mentions this issue: cmd/godoc: support internal package visibility

[jpap]

This new CL works really well for me: you can use the -internal flag or add ?m=internal on the URL. I much prefer the command-line flag because I can more quickly type the local URL into my browser and get going.

Appreciate a code review or a nomination for an appropriate contributor who can vote.

[jpap]

Hello @dmitshur! Would love to get your feedback on this CL from back in late July. If there is a more suitable reviewer, could you please suggest someone?

[dmitshur]

godoc is essentially in maintenance mode by now, and may be headed towards being replaced with a newer tool based on a more actively maintained documentation rendering library (e.g., see issue #48264 and CL 349051). As a result, it's difficult to prioritize reviewing CLs that add new features (e.g., a new flag and new ?m mode value) to this copy of godoc at this time.

I suggest providing feedback on tracking issue #40371 to move forward on this.

[stevenh]

Looks like pkgsite is making great strides on local modes, specifically allows access to local module packages including internal packages.

[mr-rosolem]

kinda difficut mercado roupas cmd/godoc: support internal package visibility