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/godoc: option to print only code #22663

Closed
dezza opened this issue Nov 10, 2017 · 7 comments
Closed

x/tools/godoc: option to print only code #22663

dezza opened this issue Nov 10, 2017 · 7 comments

Comments

@dezza
Copy link

dezza commented Nov 10, 2017

What did you do?

$ godoc -src fmt Printf

What did you expect to see?

// Printf formats according to a format specifier and writes to standard output.
// It returns the number of bytes written and any write error encountered.
func Printf(format string, a ...interface{}) (n int, err error) {
    return Fprintf(os.Stdout, format, a...)
}

What did you see instead?

use 'godoc cmd/fmt' for documentation on the fmt command

// Printf formats according to a format specifier and writes to standard output.
// It returns the number of bytes written and any write error encountered.
func Printf(format string, a ...interface{}) (n int, err error) {
    return Fprintf(os.Stdout, format, a...)
}

It would be nice if the -src option also omitted the extra info (uncommented / plain-text in first line of second source-block) (or a default template changed to exclude it). Then we could use tools like pygmentize and chroma to syntax-highlight source-code. Also it would just give a nice clean lookup of functions, which could be piped to other programs.

There is an easy workaround with
godoc -src fmt Printf | tail -n +3

But without knowing entire go I'm not sure if there are other cases where it would show extra uncommented info. So I'm leaving this issue as an idea for improvement.

@dsnet dsnet changed the title godoc option to print only code cmd/doc: option to print only code Nov 10, 2017
@dsnet dsnet changed the title cmd/doc: option to print only code x/tools/godoc: option to print only code Nov 10, 2017
@gopherbot gopherbot added this to the Unreleased milestone Nov 10, 2017
@ghost
Copy link

ghost commented Nov 11, 2017

The following might suffice, piping to awk instead of tail.

sh-4.2$ export PATH=${PATH}:/usr/share/gocode/bin
sh-4.2$ godoc -src fmt Printf | awk '/\/\//{f=1} f{print}'
// Printf formats according to a format specifier and writes to standard output.
// It returns the number of bytes written and any write error encountered.
func Printf(format string, a ...interface{}) (n int, err error) {
    return Fprintf(os.Stdout, format, a...)
}


sh-4.2$

http://nurmi-labs.blogspot.com/2015/10/awk.html

@ghost
Copy link

ghost commented Nov 11, 2017

techically I think you want to output the godoc comment and function

@dezza
Copy link
Author

dezza commented Nov 11, 2017

I know you can workaround this by stripping text with different utilities but I feel this is kinda off-topic since what is really wanted is a way to get the expected output from godoc itself and ensure that it doesn't happen in other places for some reason where you suddenly have 2 problems.

@ghost
Copy link

ghost commented Nov 11, 2017

not being the author of Go source code godoc comments followed by a function

I would think that the current authors of such code sections could be able to clarify

that there are not present any anomalies in such code sections

@agnivade
Copy link
Contributor

/cc @andybons - Do we want something like this ? We can add another flag which suppresses the extra message, but not sure if it's worth the effort.

@ghost
Copy link

ghost commented Jan 16, 2018

It seems like a narrow use case to me, and the coder who opened this issue (based on his prompt) seems to be running bash, on a Unix-like OS or using a 'Git for Windows', either of which would typically accompany a GNU awk installation. I think adding an extra flag would simply clutter up the source code.

@andybons
Copy link
Member

It would seem weird for a documentation tool to offer an option to omit said documentation.

I don't think this is within scope of godoc. You could create a tool in a rather straightforward way by making use of the stdlib go package.

@golang golang locked and limited conversation to collaborators Jan 16, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants