Request: Generating Documentation Stub for Exported Objects

[shreyaskarnik]

This is a feature request and could save some time during development and encourage adding relevant documentation via doc comments.

Per Effective Go:

All top-level, exported names should have doc comments, as should non-trivial unexported type or function declarations. See https://golang.org/doc/effective_go.html#commentary for more information about commentary conventions.

During the course of development I often come across this situation where some the linter (golint) complains about should have comment or be unexported and I often go and fix this issue by going through each of these warnings thanks to the built in highlighter in vs-code which highlights the linter issues. Having done this a couple of times this process seemed repetitive and was searching for tools to aid in creating a stub for doc comments similar to the utility provided by Go: Add Tags To Struct Fields.

Currently, I have a utility written in Go which does the following:

Identify exported items in the current project and adds a stub comment with a TODO to fill in the rest.
Before:

After:

I use the TODO Highlighter from vs-code to keep track of this to-do item in and complete the documentation. Currently the utility that I have works for all exported items. I am currently working on integrating it with vs-code to make it more useful, following existing examples.

I wanted to open this Feature Request to gauge interest on this topic so as to open a PR for this feature if this type of functionality could be handy to other users.

[m90]

That's a very personal opinion, but I feel this is kind of defeating the purpose of using golint. golint wants you to write a comment, not a TODO for doing that. If you are fine with not having comments yet, you can still build the code and see the complaint as your todo.

[ramya-rao-a]

@shreyu86 Have you tried the solution described in golang/lint#186 (comment) if what you really want is a way to ignore such warnings?

[shreyaskarnik]

@m90 thanks for the feedback. @ramya-rao-a I have used the snippet linked above to suppress warning. Was thinking about functionality to add docs in this case, for example I select a exported object and a plugin fills in the object name to serve as a starting point to continue adding documentation. For example:

func SubmitVote (userID string){
...
}

in above case the extension can generate the starting stub for the documentation and have the user complete the rest.

// SubmitVote $CURSOR
func SubmitVote (userID string){
...
}

If the above is very specific and out of scope of a extension, happy to close this issue.

[ramya-rao-a]

Including that stub (just the member name not a TODO following it) in the auto-completion list when user types // above an exported member is a good feature addition.
This way we don't circumvent the linting warning, user still has to type text after the member name.

#1005 is the feature request that is tracking exactly the same thing.
So closing this in favor of that.

[ramya-rao-a]

I have provided some pointers in #1005 (comment) if you want to get started with this

[shreyaskarnik]

Thanks for the feedback, I will check out #1005 and the pointers and start working towards a prototype.