Merge pull request #290 from kkoomen/feature/rust

Add support for Rust

Author: kkoomen

README.md

@@ -83,6 +83,7 @@ Is your favorite doc standard not supported?
 | :white_check_mark: | C++                                            | [Doxygen][doxygen]                                                           |
 | :white_check_mark: | C                                              | [Doxygen][doxygen], [KernelDoc][kerneldoc]                                   |
 | :white_check_mark: | Bash                                           | [Google][sh-google]                                                          |
+| :white_check_mark: | Rust                                           | [RustDoc][rustdoc]                                                           |
 
 # Getting started
 
@@ -153,6 +154,7 @@ Here is the full list of available doc standards per filetype:
 | `g:doge_doc_standard_cpp`        | `'doxygen_javadoc'` | `'doxygen_javadoc'`, `'doxygen_javadoc_no_asterisk'`, `'doxygen_javadoc_banner'`, `'doxygen_qt'`, `'doxygen_qt_no_asterisk'`                 |
 | `g:doge_doc_standard_c`          | `'doxygen_javadoc'` | `'kernel_doc'`, `'doxygen_javadoc'`, `'doxygen_javadoc_no_asterisk'`, `'doxygen_javadoc_banner'`, `'doxygen_qt'`, `'doxygen_qt_no_asterisk'` |
 | `g:doge_doc_standard_sh`         | `'google'`          | `'google'`                                                                                                                                   |
+| `g:doge_doc_standard_rs`         | `'rustdoc'`         | `'rustdoc'`                                                                                                                                 |
 
 ## Options
 
@@ -383,6 +385,7 @@ DoGe is licensed under the GPL-3.0 license.
 [yard]: https://www.rubydoc.info/gems/yard/file/docs/Tags.md
 [roxygen2]: https://github.com/klutometis/roxygen
 [doxygen]: http://www.doxygen.nl
+[rustdoc]: https://doc.rust-lang.org/rust-by-example/meta/doc.html
 [kerneldoc]: https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
 [sh-google]: https://google.github.io/styleguide/shell.xml#Function_Comments
 [demo-readme]: https://github.com/kkoomen/vim-doge/blob/master/doc/demos

ftplugin/rust.vim

@@ -0,0 +1,65 @@
+" ==============================================================================
+" The Rust documentation should follow the 'rustdoc' conventions.
+" see https://doc.rust-lang.org/rust-by-example/meta/doc.html
+" ==============================================================================
+
+let s:save_cpo = &cpoptions
+set cpoptions&vim
+
+let b:doge_parser = 'rust'
+let b:doge_insert = 'above'
+
+let b:doge_supported_doc_standards = doge#buffer#get_supported_doc_standards(['rustdoc'])
+let b:doge_doc_standard = doge#buffer#get_doc_standard('rs')
+let b:doge_patterns = doge#buffer#get_patterns()
+
+" ==============================================================================
+"
+" Define the pattern types.
+"
+" ==============================================================================
+
+" ------------------------------------------------------------------------------
+" Matches regular functions.
+" ------------------------------------------------------------------------------
+let s:function_pattern = {
+\  'nodeTypes': ['function_item'],
+\  'parameters': {
+\    'format': '* `{name}` - !description'
+\  },
+\}
+
+" ==============================================================================
+"
+" Define the doc standards.
+"
+" ==============================================================================
+
+call doge#buffer#register_doc_standard('rustdoc', [
+\  doge#helpers#deepextend(s:function_pattern, {
+\    'template': [
+\      '/// !description',
+\      '%(parameters|///)%',
+\      '%(parameters|/// # Arguments)%',
+\      '%(parameters|///)%',
+\      '%(parameters|/// {parameters})%',
+\      '%(unsafe|///)%',
+\      '%(unsafe|/// # Safety)%',
+\      '%(unsafe|///)%',
+\      '%(unsafe|/// !description)%',
+\      '%(errors|///)%',
+\      '%(errors|/// # Errors)%',
+\      '%(errors|///)%',
+\      '%(errors|/// !description)%',
+\      '///',
+\      '/// # Examples',
+\      '///',
+\      '/// ```',
+\      '/// !example',
+\      '/// ```',
+\    ],
+\  }),
+\])
+
+let &cpoptions = s:save_cpo
+unlet s:save_cpo

ftplugin/sh.vim

@@ -1,6 +1,6 @@
 " ==============================================================================
-" The R documentation should follow the 'Roxygen2' conventions.
-" see https://github.com/klutometis/roxygen
+" The Shell documentation should follow the 'Google' conventions.
+" see https://google.github.io/styleguide/shell.xml#Function_Comments
 " ==============================================================================
 
 let s:save_cpo = &cpoptions

package-lock.json

@@ -57,6 +57,7 @@
     "tree-sitter-php": "^0.16.2",
     "tree-sitter-python": "^0.17.1",
     "tree-sitter-ruby": "^0.17.0",
+    "tree-sitter-rust": "^0.16.0",
     "tree-sitter-typescript": "^0.16.3"
   },
   "devDependencies": {

package.json

@@ -8,4 +8,5 @@ export enum Language {
   RUBY = 'ruby',
   LUA = 'lua',
   JAVA = 'java',
+  RUST = 'rust',
 }

src/constants.ts

@@ -6,6 +6,7 @@ import Lua from 'tree-sitter-lua';
 import PHP from 'tree-sitter-php';
 import Python from 'tree-sitter-python';
 import Ruby from 'tree-sitter-ruby';
+import Rust from 'tree-sitter-rust';
 import TypeScript from 'tree-sitter-typescript/tsx';
 import { Language } from './constants';
 import { ValueOf } from './types';
@@ -21,6 +22,7 @@ export function loadParserPackage(language: ValueOf<Language>): any {
     [Language.RUBY]: Ruby,
     [Language.LUA]: Lua,
     [Language.JAVA]: Java,
+    [Language.RUST]: Rust,
   };
 
   if (!Object.keys(languages).includes(language as string)) {

src/helpers.ts

@@ -9,6 +9,7 @@ import { LuaParserService } from './lua.service';
 import { PhpParserService } from './php.service';
 import { PythonParserService } from './python.service';
 import { RubyParserService } from './ruby.service';
+import { RustParserService } from './rust.service';
 import { TypeScriptParserService } from './typescript.service';
 
 export type ParserService =
@@ -20,7 +21,8 @@ export type ParserService =
   | BashParserService
   | RubyParserService
   | LuaParserService
-  | JavaParserService;
+  | JavaParserService
+  | RustParserService;
 
 export function getParserService(
   language: ValueOf<Language>,
@@ -54,6 +56,9 @@ export function getParserService(
     case Language.JAVA:
       return new JavaParserService(...args);
 
+    case Language.RUST:
+      return new RustParserService(...args);
+
     default:
       // prettier-ignore
       console.error(`Could not get parser service for unknown language: ${language}`);

src/parsers/index.ts

@@ -0,0 +1,98 @@
+import { SyntaxNode } from 'tree-sitter';
+import { BaseParserService } from './base-parser.service';
+import { CustomParserService } from './custom-parser-service.interface';
+
+enum NodeType {
+  FUNCTION_ITEM = 'function_item',
+}
+
+export class RustParserService
+  extends BaseParserService
+  implements CustomParserService {
+  constructor(
+    readonly rootNode: SyntaxNode,
+    private readonly lineNumber: number,
+    private readonly nodeTypes: string[],
+  ) {
+    super();
+  }
+
+  public traverse(node: SyntaxNode): void {
+    if (
+      node.startPosition.row === this.lineNumber &&
+      this.nodeTypes.includes(node.type) &&
+      this.done === false
+    ) {
+      switch (node.type) {
+        case NodeType.FUNCTION_ITEM: {
+          this.result = {
+            name: null,
+            parameters: [],
+            unsafe: false,
+            errors: false,
+          };
+          this.runNodeParser(this.parseFunction, node);
+          break;
+        }
+
+        default: {
+          console.error(`Unable to handle node type: ${node.type}`);
+          break;
+        }
+      }
+    } else if (node.childCount > 0) {
+      node.children.forEach((childNode: SyntaxNode) => {
+        this.traverse(childNode);
+      });
+    }
+  }
+
+  private parseFunction(node: SyntaxNode): void {
+    node.children.forEach((childNode: SyntaxNode) => {
+      switch (childNode.type) {
+        case 'identifier': {
+          this.result.name = childNode.text;
+          break;
+        }
+
+        case 'function_modifiers': {
+          childNode.children.forEach((n: SyntaxNode) => {
+            if (n.type === 'unsafe') {
+              this.result.unsafe = true;
+            }
+          });
+          break;
+        }
+
+        case 'generic_type': {
+          const hasResultReturnType = childNode.children
+            .filter(
+              (n: SyntaxNode) =>
+                n.type === 'type_identifier' && n.text === 'Result',
+            )
+            .shift();
+          if (hasResultReturnType) {
+            this.result.errors = true;
+          }
+          break;
+        }
+
+        case 'parameters': {
+          childNode.children
+            .filter((n: SyntaxNode) => n.type === 'parameter')
+            .forEach((child: SyntaxNode) => {
+              this.result.parameters.push({
+                name: child.children
+                  .filter((n: SyntaxNode) => n.type === 'identifier')
+                  .shift()?.text,
+              });
+            });
+          break;
+        }
+
+        default:
+          break;
+      }
+    });
+  }
+}

src/parsers/rust.service.ts

@@ -7,3 +7,4 @@ declare module 'tree-sitter-bash';
 declare module 'tree-sitter-ruby';
 declare module 'tree-sitter-lua';
 declare module 'tree-sitter-java';
+declare module 'tree-sitter-rust';

src/vim-doge.d.ts

@@ -0,0 +1,91 @@
+# ==============================================================================
+# Functions with parameters.
+# ==============================================================================
+Given rust (impl methods with parameters):
+  struct Person {
+      name: String,
+  }
+  
+  impl Person {
+      fn new(name: &str) -> Person {
+          Person {
+              name: name.to_string(),
+          }
+      }
+  
+      pub fn hello(&self) -> u8 {
+          return 0;
+      }
+  }
+
+Do (trigger doge):
+  :6\<CR>
+  \<C-d>
+  :23\<CR>
+  \<C-d>
+
+Expect rust (generated comments with Arguments and Examples sections):
+  struct Person {
+      name: String,
+  }
+  
+  impl Person {
+      /// [TODO:description]
+      ///
+      /// # Arguments
+      ///
+      /// * `name` - [TODO:description]
+      ///
+      /// # Examples
+      ///
+      /// ```
+      /// [TODO:example]
+      /// ```
+      fn new(name: &str) -> Person {
+          Person {
+              name: name.to_string(),
+          }
+      }
+  
+      /// [TODO:description]
+      ///
+      /// # Examples
+      ///
+      /// ```
+      /// [TODO:example]
+      /// ```
+      pub fn hello(&self) -> u8 {
+          return 0;
+      }
+  }
+
+# ==============================================================================
+# Functions with errors and safety section
+# ==============================================================================
+Given rust (impl methods with Errors and Safety section):
+  pub unsafe fn foo(foo: usize) -> Result<(), FooError> {}
+
+Do (trigger doge):
+  \<C-d>
+
+Expect rust (generated comments with Arguments, Safety, Errors and Examples sections):
+  /// [TODO:description]
+  ///
+  /// # Arguments
+  ///
+  /// * `foo` - [TODO:description]
+  ///
+  /// # Safety
+  ///
+  /// [TODO:description]
+  ///
+  /// # Errors
+  ///
+  /// [TODO:description]
+  ///
+  /// # Examples
+  ///
+  /// ```
+  /// [TODO:example]
+  /// ```
+  pub unsafe fn foo(foo: usize) -> Result<(), FooError> {}