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

Jump to bottom

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

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

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

gertcuykens opened this issue Jun 13, 2019 · 10 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.14

Comments

@gertcuykens
Copy link
Contributor

gertcuykens commented Jun 13, 2019 •
edited

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

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

gertcuykens commented Jun 13, 2019 •
edited

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

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
@agnivade agnivade added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Jun 13, 2019
@gopherbot
Copy link

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

@robpike
Copy link
Contributor

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

robpike commented Jun 27, 2019

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

@gertcuykens
Copy link
Contributor Author

gertcuykens commented Jun 27, 2019 •
edited

I agree :) , what about

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

Patchset 3 pushed

@robpike
Copy link
Contributor

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

gertcuykens commented Jun 27, 2019 •
edited

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

robpike commented Jun 27, 2019

This is looking good.

@andybons andybons added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels Jul 8, 2019
@andybons andybons modified the milestones: Unreleased, Go1.14 Jul 8, 2019
@golang golang locked and limited conversation to collaborators Sep 18, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.14
Development

No branches or pull requests
5 participants
@andybons @gertcuykens @agnivade @robpike @gopherbot