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

cmd/doc: add option to suppress showing package docs #32597

Open
gertcuykens opened this issue Jun 13, 2019 · 10 comments

Comments

Projects
None yet
5 participants
@gertcuykens
Copy link

commented Jun 13, 2019

A go doc -tree output please would be awesome.

Currently there is no way for go doc to output a clean single line separated definitions of types, functions, vars and consts.

For example go doc | fzf the intro of a package is scrambled between the output for a fuzzy finder
image

@gopherbot gopherbot added this to the Unreleased milestone Jun 13, 2019

@agnivade agnivade changed the title x/tools/cmd/godoc: go doc -tree | fzf cmd/doc: add -tree option Jun 13, 2019

@agnivade

This comment has been minimized.

Copy link
Member

commented Jun 13, 2019

Please show an example of what exactly do you mean by a tree output. And how will this help a fuzzy finder. According to your screenshot, each types are already separated by a new line. So I am not exactly sure what you mean by

clean single line separated definitions of types, functions, vars and consts.

@gertcuykens

This comment has been minimized.

Copy link
Author

commented Jun 13, 2019

Yep this is the output of go doc

package moss // import "."

Package moss stands for "memory-oriented sorted segments", and provides a
data structure that manages an ordered Collection of key-val entries, with
optional persistence.

The design is similar to a simplified LSM tree (log structured merge tree),
but is more like a "LSM array", in that a stack of immutable, sorted key-val
....

var StorePageSize = 4096
var StorePrefix = "data-"
var StoreSuffix = ".moss"
var StoreVersion = uint32(4)
func ByteSliceToUint64Slice(in []byte) ([]uint64, error)
func FormatFName(seq int64) string
func HeaderLength() uint64
func OpenStoreCollection(dir string, options StoreOptions, persistOptions StorePersistOptions) (*Store, Collection, error)
func ParseFNameSeq(fname string) (int64, error)
func ToOsFile(f File) *os.File
func Uint64SliceToByteSlice(in []uint64) ([]byte, error)
type Batch interface{ ... }
type BatchOptions struct{ ... }
type Collection interface{ ... }
    func NewCollection(options CollectionOptions) (Collection, error)
type CollectionOptions struct{ ... }
type CollectionStats struct{ ... }
type CompactionConcern int
    const CompactionDisable CompactionConcern = iota ...
type EntryEx struct{ ... }
type Event struct{ ... }
type EventKind int
    const EventKindCloseStart EventKind = 1 + iota ...
type File interface{ ... }
type FileRef struct{ ... }
type Footer struct{ ... }
    func ReadFooter(options *StoreOptions, file File) (*Footer, error)
    func ScanFooter(options *StoreOptions, fref *FileRef, fileName string, pos int64) (*Footer, error)
type Header struct{ ... }
...

If go doc -tree would only ouput the following, (same but without the intro) then a fuzzy finder will not scramble intro lines in the result

var StorePageSize = 4096
var StorePrefix = "data-"
var StoreSuffix = ".moss"
var StoreVersion = uint32(4)
func ByteSliceToUint64Slice(in []byte) ([]uint64, error)
func FormatFName(seq int64) string
func HeaderLength() uint64
func OpenStoreCollection(dir string, options StoreOptions, persistOptions StorePersistOptions) (*Store, Collection, error)
func ParseFNameSeq(fname string) (int64, error)
func ToOsFile(f File) *os.File
func Uint64SliceToByteSlice(in []uint64) ([]byte, error)
type Batch interface{ ... }
type BatchOptions struct{ ... }
type Collection interface{ ... }
    func NewCollection(options CollectionOptions) (Collection, error)
type CollectionOptions struct{ ... }
type CollectionStats struct{ ... }
type CompactionConcern int
    const CompactionDisable CompactionConcern = iota ...
type EntryEx struct{ ... }
type Event struct{ ... }
type EventKind int
    const EventKindCloseStart EventKind = 1 + iota ...
type File interface{ ... }
type FileRef struct{ ... }
type Footer struct{ ... }
    func ReadFooter(options *StoreOptions, file File) (*Footer, error)
    func ScanFooter(options *StoreOptions, fref *FileRef, fileName string, pos int64) (*Footer, error)
type Header struct{ ... }
...

For me the following is much fuzzy finder friendly because no scrambled intro text is ever in the search result and everything is exactly ordered in one line

gert@gert ~/Desktop/moss:master> go doc > index.txt
gert@gert ~/Desktop/moss:master> remove intro from index.txt manually then do
gert@gert ~/Desktop/moss:master> cat index.txt | fzf

image

Notice the difference between the first screenshot and this one for the same search

@agnivade

This comment has been minimized.

Copy link
Member

commented Jun 13, 2019

I see. I thought -tree meant a tree like structure. So IIUC, you just do not want the package doc(or rather any sort of docs) to appear for fuzzy finder to work properly. I will update the title appropriately and leave it to @robpike to make a call.

@agnivade agnivade changed the title cmd/doc: add -tree option cmd/doc: add option to suppress showing package docs Jun 13, 2019

@gopherbot

This comment has been minimized.

Copy link

commented Jun 27, 2019

Change https://golang.org/cl/184017 mentions this issue: cmd/doc: add option to suppress showing package docs

@robpike

This comment has been minimized.

Copy link
Contributor

commented Jun 27, 2019

I have no problem with the idea, but the flag name chosen in the CL (go doc -sym) is both misleading (all go doc does is show symbols) and poorly explained. Hoping a better suggestion will come.

Once that's sorted, the CL will need to update the go command as well.

@robpike

This comment has been minimized.

Copy link
Contributor

commented Jun 27, 2019

The idea you're looking for is "short" or "compact" or "simple", not "symbol".

@gertcuykens

This comment has been minimized.

Copy link
Author

commented Jun 27, 2019

I agree :) , what about

flagSet.BoolVar(&short, "short", false, "short summary of symbols without package docs")

Patchset 3 pushed

@robpike

This comment has been minimized.

Copy link
Contributor

commented Jun 27, 2019

It's not just package docs, though, is it? Other things are suppressed too, are they not? Or at least the intent should be. I think what you're trying to get (we could be on different paths here) is a way to get just a list of the symbols with a concise summary of their types, free of documentation.

@gertcuykens

This comment has been minimized.

Copy link
Author

commented Jun 27, 2019

Correct, a one line representation for each symbol without any other text line that isn't a symbol. I can change the docs to

flagSet.BoolVar(&short, "short", false, "one line representation for each symbol")

and

	-short
		One line representation for each symbol.

So if am not mistaken just the output of

	pkg.valueSummary(pkg.doc.Consts, false)
	pkg.valueSummary(pkg.doc.Vars, false)
	pkg.funcSummary(pkg.doc.Funcs, false)
	pkg.typeSummary()

wil give that result.

So I probably forgot to short out this too, will do in a new Patchset

        if !short {
		pkg.bugs()
	}
@robpike

This comment has been minimized.

Copy link
Contributor

commented Jun 27, 2019

This is looking good.

@andybons andybons added NeedsFix and removed NeedsDecision labels Jul 8, 2019

@andybons andybons modified the milestones: Unreleased, Go1.14 Jul 8, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.