cmd/godoc: -sync doesn't work on Windows, also bad documentation

[gopherbot]

by trolleriprofessorn:

cmd/godoc: /pkg doesn't show changes to dir structure

I haven't found a way to make the godoc server update the /pkg listing
without restarting the server. Please add this functionality (perhaps
with an update button on the web page) or make it more discoverable.

Which revision are you using? 3355c03e3e2c+

[minux]

Comment 1:

You can try this on Unix:
godoc -sync="true" -sync_minutes=1 -http=:8080
It will automatically refresh the /pkg dir. structure every minute.
If you are on Windows, though, this won't work.

Labels changed: added os-windows.

Status changed to Accepted.

[minux]

Comment 2:

On windows, use this (with CL 5796054):
godoc -sync="exit 0" -sync_minutes=1 -http=:8080

Labels changed: added priority-go1, removed priority-triage.

Owner changed to @minux.

[gopherbot]

Comment 3 by trolleriprofessorn:

I would never have figured out what "command" to use from reading
the current godoc documentation:
-sync="command"
    if this and -sync_minutes are set, run the argument as a
    command every sync_minutes; it is intended to update the
    repository holding the source files.
Also, there is nothing to indicate to the user of the web pages
that a refresh is available. I like the solution used by GoPkgDoc.
It has better discoverability. At the bottom of a package page,
you find the following message:
  GoPkgDoc generated this page from the XXX source code just now. ⟲
On mouse-over, the circular arrow shows the message
  "Refresh this page from the source"
  
Would it be possible to offer something similar?

[minux]

Comment 4:

I agree the godoc command document isn't clear about -sync.
For the other question, I think I should leave it to others.

[bradfitz]

Comment 5:

I vote to remove the -sync flag and code.
I think it's unused and doesn't serve enough purpose.  Few people work on the go tip,
and most can just restart their local godoc or use tip.golang.org.
Robert, Andrew, Russ, ...?

[rsc]

Comment 6:

I agree.  We don't use -sync anymore: delete it.
However, there is probably still an issue here: godoc should refresh its in-memory cache
if things have changed.

[bradfitz]

Comment 7:

I think cache coherency is a separate issue and one we already have with tip.golang.org
(you'll recall that tip.golang.org just re-execs itself whenever it detects a new
commit).

[bradfitz]

Comment 8:

This issue was closed by revision d46438c.

Status changed to Fixed.

[gopherbot]

Comment 9 by trolleriprofessorn:

Even though tip.golang.org can work around stale directory listings, there is still an
issue for people using godoc to browse code besides the go project itself. Also, not
everyone will be able to restart the server. I'm sure some godoc servers will be guarded
by systems managers... :)
If it's not feasible to regenerate the listings, a stopgap measure would be to turn the
timestamps flag on by default. Then the behavior will at least be transparent.

[robpike]

Comment 10:

This issue was closed by revision 733ee91.