Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
jacobsa opened this issue Aug 10, 2015 · 13 comments
Open

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

jacobsa opened this issue Aug 10, 2015 · 13 comments
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone

Comments

@jacobsa
Copy link
Contributor

jacobsa commented Aug 10, 2015

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:

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:

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
Copy link
Contributor

adg commented Aug 10, 2015

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
Copy link
Contributor Author

jacobsa commented Aug 10, 2015

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.

@rsc rsc added this to the Unplanned milestone Aug 10, 2015
@agnivade agnivade changed the title cmd/godoc: show internal packages when explicitly requested x/tools/cmd/godoc: show internal packages when explicitly requested Apr 25, 2018
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Sep 12, 2019
@perillo
Copy link
Contributor

perillo commented Feb 3, 2020

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
Copy link
Contributor

akavel commented Jul 27, 2020

@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
Copy link
Contributor

nhooyr commented Jul 27, 2020

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

@tonglil
Copy link

tonglil commented Apr 27, 2021

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
Copy link
Contributor

jpap commented Jul 22, 2021

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
Copy link

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

@jpap
Copy link
Contributor

jpap commented Jul 24, 2021

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
Copy link
Contributor

jpap commented Sep 28, 2021

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
Copy link
Contributor

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.

@dmitshur dmitshur added FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Sep 28, 2021
@stevenh
Copy link
Contributor

stevenh commented May 5, 2023

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

@mr-rosolem

This comment was marked as spam.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests