pavlitsky / vscode-yard

YARD comments generator for Visual Studio Code

YARD Documenter

Extension generates YARD documentation comments for Ruby source code.

See Readme for more information on this tool.

Features

Extension automatically prepends definitions of methods, classes etc with documentation snippets. No need to remember a formatting tags and styling, just type and describe your code.

It's able to document:

• Methods: instance methods, initializers, class methods.
• Classes and Modules.
• Constants.
• Attributes accessors (attr_reader, attr_writer, attr_accessor and more).

Methods named in ASCII and Japanese are supported.

Usage

Position cursor on a definition you wish to document.

def foo(bar, baz = false) # <- put cursor at any place of this line
end

Hit Ctrl+Alt+Enter (Option+Command+Enter on macOS) or invoke Document with YARD from the command palette.

  #
  # <Description>
  #
  # @param [<Type>] bar <description>
  # @param [<Type>] baz <description>
  #
  # @return [<Type>] <description>
  #
  def foo(bar, baz = false)
  end

Documentation snippet appears on top of the method.

Use Tab and Shift+Tab keys to navigate and fill in placeholders.

  #
  # An example instance method description.
  #
  # @param [Integer] bar first param used for demonstration
  # @param [Boolean] baz second param with a default value
  #
  # @return [nil] nothing returned so it's always nil
  #
  def foo(bar, baz = false)
  end

Done!

Another snippets examples, default spacers setup:

#
# Class to retry and fail.
#
# @author Author Name <[email protected]>
#
class Foo
  # @return [Integer] count of retries performed before failing
  RETRIES_COUNT=3

  # @return [Boolean] retry operation result
  attr_accessor :succeed

  #
  # Retry something.
  #
  # @return [Boolean] processing result, true if succeed
  #
  def retry
    RETRIES_COUNT.times { puts 'Retrying...' }
    @succeed = false
  end
end

Minimal setup:

# Class to retry and fail.
class Foo
  # @return [Integer] count of retries performed before failing
  RETRIES_COUNT=3

  # @return [Boolean] retry operation result
  attr_accessor :succeed

  # Retry something.
  # @return [Boolean] processing result, true if succeed
  def retry
    RETRIES_COUNT.times { puts 'Retrying...' }
    @succeed = false
  end
end

Feel free to append any needed tags like @note, @example, @see manually after snippet filled in.

Details

List of generated tags: @author, @option, @param, @return.

Configuration

Insertion of empty lines are configurable to make it able to tune between a curt and verbose documentation styles.

"yard.spacers.beforeDescription" // Prepend an empty line to descriptive texts
"yard.spacers.afterDescription" // Append an empty line to descriptive texts
"yard.spacers.beforeTags" // Prepend an empty line to all method's tags
"yard.spacers.separateTags" // Separate method's tags of the same name (@params and @return) with an empty line
"yard.spacers.afterTags" // Append an empty line to all method's tags
"yard.spacers.beforeSingleTag" // Prepend an empty line to directives or single tags (for example constants)
"yard.spacers.afterSingleTag" // Append an empty line to directives or single tags (for example constants)
"yard.tags.author" // Append @author tag to Class and Module documentation
"yard.tags.paramNameBeforeType" // Print param name before its type (for example '@param username [String]')

TODO

• Ability to document blocks: @yield, @yieldparam, @yieldreturn.
• Support for non-empty options hash parameters.
• Resolve @author information from environment or settings.
• (killer feature 🔥) Ability to update existing documentation.
• (maybe) Editor snippets for tags (@option, @param etc) or tags autocompletion
• (maybe) A better support for array / keyword args splats, see comment.

Troubleshooting

If hotkey isn't working open VS Code Keyboard Shortcuts and check for keybinging conflicts.

This also may happen if destination is already documented. In this case extension silently does nothing.

vscode-yard's Issues

Doesn't generate method documentation for methods that aren't alphanumeric

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.

Don't document methods with malformed parameters

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

Order in params documentation

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.

Incorrect MacOs Keyboard Shortcut Documentation

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

New template

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?

Please publish it in open-vsx.org

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)

Wrong syntax for @!attribute

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!

Should the param name go before the type?

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?

Add def methods without parentheses

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.