View functions/methods in main package with godoc

[Peter Waller]

Hi All,

The godoc states that if you set the "m" URL parameter to "all", then it will "show documentation for all declarations, not just the exported ones".

I take it this doesn't apply to packages named "main" for some reason?

For example, it would have been nice to see the methods inside this package:

http://golang.org/cmd/api/?m=all

(picked as an arbitrary public link)

... even though I can't call them.

I want this because we have an application with a fairly large "main". Granted, it would be better if the functionality were split into packages, but that's even harder to do when I can't view the godoc for it!

Thanks,

- Peter

[Mateusz Czapliński]

On Monday, August 24, 2015 at 3:41:04 PM UTC+2, Peter Waller wrote:

The godoc states that if you set the "m" URL parameter to "all", then it will "show documentation for all declarations, not just the exported ones".

I take it this doesn't apply to packages named "main" for some reason?

I want this because we have an application with a fairly large "main". Granted, it would be better if the functionality were split into packages, but that's even harder to do when I can't view the godoc for it!

I don't know if it's possible in godoc -http, but there are some workarounds/alternatives:

1. Go 1.5's new command "go doc" (note: not the same as "godoc") has option "-cmd" which reportedly allows that -- see: https://golang.org/cmd/go/#hdr-Show_documentation_for_package_or_symbol

2. I have a fork of the "go-explorer" plugin for Vim with such feature enabled, at: https://github.com/akavel/go-explorer/commits/show_cmds_identifiers (note: you must clone this specific branch); it might get added into go-explorer in future in some form, see: https://github.com/garyburd/go-explorer/issues/6

/M.

[Peter Waller]

On 24 August 2015 at 16:27, Mateusz Czapliński <czap...@gmail.com> wrote:

I don't know if it's possible in godoc -http, but there are some workarounds/alternatives:

1. Go 1.5's new command "go doc" (note: not the same as "godoc") has option "-cmd" which reportedly allows that -- see: https://golang.org/cmd/go/#hdr-Show_documentation_for_package_or_symbol

Unfortunately, this doesn't show the contents of structs, in particular, making it not so useful to me.

 

2. I have a fork of the "go-explorer" plugin for Vim with such feature enabled, at: https://github.com/akavel/go-explorer/commits/show_cmds_identifiers (note: you must clone this specific branch); it might get added into go-explorer in future in some form, see: https://github.com/garyburd/go-explorer/issues/6

That's great and all, but I really want something as simple as `godoc -http` which I can point colleagues at, who might not necessarily be using VIM.

Go devs - is there a particular reason `godoc -http` has no (apparent) way to get at symbols in cmds, or is it just an oversight? Is it worth a feature request?

[Rob Pike]

It is on purpose, since usually when one looks at main, one wants the usage, not the internal types.

-rob

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Peter Waller]

On 25 August 2015 at 12:11, Rob Pike <r...@golang.org> wrote:

It is on purpose, since usually when one looks at main, one wants the usage, not the internal types.

Is it on purpose that it is not possible even if one *does* want the usage (and is willing to specify additional parameters), such as when they're in my position?

To be clear, I'm not asking to change the current default behaviour. Just that I face more than one project where it would be a very useful ability to request to view the usual godoc for a main package.

[Rob Pike]

I can't speak to the minutiae of godoc, but with 1.5 the new go doc (sic) will give you all the information about the internals if you ask it. Try

cd go/src/cmd/doc

go doc -cmd -u Package

for an example. Basically, the cmd flag makes it treat main the same as any other package.

-rob

[Peter Waller]

On 25 August 2015 at 13:49, Rob Pike <r...@golang.org> wrote:

the new go doc (sic) will give you all the information about the internals if you ask it.

Sadly, this is not true. My output looks like this, which is missing which fields are present:

type PerformanceTiming struct { ... }

.. and the documentation comments!

However, that's great and all, but it's still not the same as `godoc -http`, which I can use to send links to my colleagues and comes with the lovely features of hyperlinking and search, for example.

To first order though, it would make me happy if there were something that at least showed the fields and documentation comments on functions, types and fields.

[Mateusz Czapliński]

On Tuesday, August 25, 2015 at 3:06:11 PM UTC+2, Peter Waller wrote:

However, that's great and all, but it's still not the same as `godoc -http`, which I can use to send links to my colleagues and comes with the lovely features of hyperlinking and search, for example.

To first order though, it would make me happy if there were something that at least showed the fields and documentation comments on functions, types and fields.

Hmmm, then one more shot: you could try if gowalker wouldn't work for you:
  https://github.com/Unknwon/gowalker
It seems to show internals of commands, and with links and comments -- see for example:
  https://gowalker.org/github.com/akavel/rsrc
(not many comments there, but there's one e.g. at: https://gowalker.org/github.com/akavel/rsrc#GRPICONDIR)

/Mateusz.

[whm...@gmail.com]

In my case, my main function is just handles a bunch of http requests.  All the data retrieval and return values from the requests are in their own packages and are documentable. The problem with an  http request, is it isn't even "self" documenting, that is, you may have different parameters as part of the data sent, like the id of some database record.

It would be nice to document that part of the http handler with godoc, something like "parameter id expects the database id of the record", or something like that. I know you can see what parameters the http request needs by looking at the source code, but I think it would a little neater if the main function could have generated docs, like the rest of the app's packages

One solution would be to move the actual handler function to another package and document it there.  In my app, all the routing and returning is in one spot (main), and that's where I think it should be.