pavlitsky / vscode-yard Goto Github PK

Hi @pavlitsky

Thanks for developing this cool plugin！👍❤️

I have some simple advice for the generated docstring template.

Now the template is:

    #
    # <Description>
    #
    # @param [<Type>] arg1 <description>
    # @param [<Type>] arg2 <description>
    #
    # @return [<Type>] <description>
    #
    def hello(arg1, arg2)

But I think the template below is clearer.

    # <Description>
    #
    # @param arg1 [<Type>] <description>
    # @param arg2 [<Type>] <description>
    #
    # @return [<Type>] <description>
    #
    def hello(arg1, arg2)

I'm sorry I don't have TypeScript skills to do it myself. So, could you please make a patch if you agree with the change?

README.MD file incorrectly shows "Cmd+Alt+Enter on macOS", There is no ALT key on a MacOS keyboard.

Hello,

It seems to me the correct order is
@param #{param_name} [#{type}] #{description}

while this plugin generates
@param [#{type}] #{param_name} #{description}.

Am I wrong ? I got this from https://www.rubydoc.info/gems/yard/file/docs/Tags.md#Hashes for example.

YARD documentation indicates the the parameter name goes before the type:
https://www.rubydoc.info/gems/yard/file/docs/Tags.md#param

# @param url [String] the URL of the page to download
# @param directory [String] the name of the directory to save to
def load_page(url, directory: 'pages') end

The snippet generated by this plugin looks like this, with the field names after the type name:

#
# <Description>
#
# @param [<Type>] url <description>
# @param [<Type>] directory <description>
#
# @return [<Type>] <description>
#
def load_page(url, directory: 'pages') end

I've seen both in the wild though I believe the former is preferred - should this be updated?

Just wondering if it's possible to include also methods without parentheses, like:

def some_method parameter_1 parameter_2
end

I was trying to add a test, but I'm getting this:

/usr/lib/electron/electron --debugBrkPluginHost=31500 --debugId=d56f2c9b-c651-4044-8458-069c1e343f5f /home/pablo/code/vscode/vscode-yard/src/test/project --extensionDevelopmentPath=/home/pablo/code/vscode/vscode-yard --extensionTestsPath=/home/pablo/code/vscode/vscode-yard/out/test 
Error launching app
Unable to find Electron app at /home/pablo/code/vscode/vscode-yard/src/test/project
Cannot find module '/home/pablo/code/vscode/vscode-yard/src/test/project'

What I did:

1. Clone the repo
2. npm install
3. Open the folder on VS Code
4. Debug sidebar
5. Extension tests
6. Little green arrow

Nevertheless, I'm not that familiarized with javascript/typescript, but I was going to give it a go.

The YARD documentation states that:

@!attribute [r | w | rw] attribute_name
   Indented attribute docstring

Note: This directive should only be used if there is no explicit attr_* declaration for the attribute in > any source files (i.e., the attribute is declared dynamically via meta-programming). In all other cases, add documentation to the attribute declaration itself.

The correct documentation for an attribute thus looks like:

# @return [MissionType] Mission to work with
attr_reader :mission

And indeed it works well with Yard.

But the extension generates this comment:

# @!attribute [r] mission
#   @return [MissionType] Mission to work with
attr_reader :mission

And this is not understood by Yard.

Would it be possible to update the snippet in this sense?

Thanks for the very useful work!

Open VSX Registry (https://open-vsx.org/) is a free and opensource registry for VSCode alternatives, like VSCodium and Eclipse Theia.

You can learn about it here: https://www.eclipse.org/legal/open-vsx-registry-faq/#faq-1 (and why it exists)

You can also reach out documentation https://github.com/eclipse/openvsx/wiki and how to publish on the registry (it's very similar)

Thanks for creating this plugin!

I have noticed that the plugin doesn't generate method documentation if the method isn't alphanumeric. For example

def |(other)

end

If you ask the plugin to generate method documentation using the hotkey, nothing happens.

Add basic validation for method's parameters. If they're invalid then don't document either entire method or only skip its parameters.

Bad params examples:

def foo(bar, baz qux)
end

def foo ; end