yard-rustdoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79bdb3aec8e1f714e0171aa730ac8f7ae76a2c03a833469e881c509965b2e570
+  data.tar.gz: 3b9c82a3687ac3dd58f94932e63f1a71ef390314f7a1940dd2b1f2618aec8845
+SHA512:
+  metadata.gz: eff3df27844e46ad1ff348af7149e7e87758249f0478afbd88b68692ba84338a9b1a970091b14f703491b6cf78738ebb61b16dc3eae2bc8c49c450ea9f1a2d7d
+  data.tar.gz: be52e56f4bb91b3047b57b8fd1518b9c094e74b0601fdc32349c3e425beac0a6914589997955a9fc37f2a0673c35336cf77dd77b269284578d53092d4f7d26a2

data/README.md

@@ -0,0 +1,120 @@
+# YARD::Rustdoc
+
+YARD plugin for documenting Magnus-based Rust gems. Supports writing class
+documentation on Struct and method documentation on Struct methods.
+
+**Note**: WIP, not released.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yard-rustdoc'
+```
+
+Load the plugin through `--plugin rustdoc` (e.g. in your project's `.yardopts`).
+See `test/samples/example-ext` for full example.
+
+## Usage
+
+1. Write YARD-compatible documentation in Rust documentation block
+   (`///` or `//!`), and tag them with `@yard`.
+
+2. Generate Rustdoc as JSON:
+
+   ```sh
+     cargo +nightly rustdoc -p path/to/extension -- \
+        -Zunstable-options --output-format json  \
+        --document-private-items
+   ```
+
+   `nightly` is required because the JSON format isn't stable yet.  
+   `--document-private-items` is included so that you don't have to make
+   everything in the crate public.
+
+3. Run YARD on Ruby files and the Rustdoc's JSON:
+
+   ```sh
+   yard lib path/to/rustdoc.json
+   ```
+
+### Writing documentation
+
+YARD::Rustdoc only targets docblocks starting with `@yard` so that you can
+still write Rust-style docblocks for non-Ruby parts of your crate.
+
+#### Examples
+
+The class name will be extracted from Magnus' `class =`.
+
+```rust
+/// @yard
+/// High-level documentation for Foo::Bar.
+#[magnus(class = "Foo::Bar")]
+pub struct Bar { }
+```
+
+The `@rename` tag renames the class to `Foo::Baz`.
+
+```rust
+/// @yard
+/// @remame Foo::Baz
+pub struct InnerName { }
+```
+
+Defines `Foo::Bar.new` -- class method because the first argument isn't `self`.
+
+```rust
+impl Bar {
+    /// @yard
+    /// @return [Foo::Bar]
+    fn build() -> Self {}
+}
+```
+
+Defines `Foo::Bar#baz`:
+
+```rust
+impl Bar {
+    /// @yard
+    fn baz(&self) {}
+}
+```
+
+Specifies the method's name and params with `@def`. This lets YARD know which params
+are required, optional, keyword arguments, etc.
+
+`@def` must be a single, valid ruby method definition, without the `end`.
+
+```rust
+impl Bar {
+    /// @yard
+    /// @def qux=(val = "")
+    /// @param val [Object]
+    fn write_qux(&self, val: Value) {}
+}
+```
+
+This will be ignored as it's not tagged with `@yard`.
+
+```rust
+impl Bar {
+    fn secret {}
+}
+```
+
+#### Tips
+
+YARD's syntax differs from what Rustdoc expects. Linters you man want to disable:
+
+```rust
+#![allow(rustdoc::broken_intra_doc_links)]
+#![allow(rustdoc::invalid_html_tags)]
+```
+
+## Development
+
+Run tests with `rake`. The tests use a sample project located in
+`test/samples/example-ext`. To regenerate its json doc, run `rake doc:rustdoc`
+from that directory. See the test project's Rakefile for details.

data/lib/yard-rustdoc/def_parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "syntax_tree"
+
+module YARD
+  module Rustdoc
+    class DefParser
+      # The name of the `def`'d method
+      attr_reader(:name)
+
+      # The params of the `def`'d method
+      # @return [Array<[String, [String, nil]]>] An array of tuple where 0 is
+      #   the name of the arg with its specifier (&, **, :) and 1 is the default.
+      attr_reader(:parameters)
+
+      def initialize(string)
+        @string = string
+        @name = nil
+        @parameters = []
+        parse!
+      end
+
+      private
+
+      def parse!
+        string = "def #{@string}; end"
+        def_node = begin
+          SyntaxTree.parse(string) # Program
+            .child_nodes.first # Statements
+            .child_nodes.first # Def
+        rescue => e
+          log.debug(e)
+          return log.warn("failed to extract def node from '#{@string}'\n  #{e.message}")
+        end
+        @name = def_node.name.value
+
+        params = def_node.params
+        params = params.contents if params.is_a?(SyntaxTree::Paren)
+
+        params.requireds.each { |name| add_param(name) }
+        params.optionals.each { |name, default| add_param(name, default) }
+        add_param(params.rest) if params.rest
+        params.posts.each { |name| add_param(name) }
+        params.keywords.each { |name, default| add_param(name, default) }
+        add_param(params.keyword_rest) if params.keyword_rest
+
+        add_param(params.block) if params.block
+      end
+
+      def format(node)
+        formatter = SyntaxTree::Formatter.new(nil)
+        node.format(formatter)
+        formatter.flush
+        formatter.output
+      end
+
+      def add_param(node, default = nil)
+        default = format(default) if default
+
+        @parameters << [format(node), default]
+      end
+    end
+  end
+end

data/lib/yard-rustdoc/handlers.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module YARD::Handlers
+  module Rustdoc
+    class Base < YARD::Handlers::Base
+      include YARD::Parser::Rustdoc
+
+      def self.statement_class(klass = nil)
+        @statement_classes ||= []
+        @statement_classes << klass
+
+        nil
+      end
+
+      def self.handles?(statement, processor)
+        handles = true
+        if @statement_classes.any?
+          handles &&= @statement_classes.any? { |klass| statement.is_a?(klass) }
+        end
+
+        handles
+      end
+
+      def register_file_info(object, file = statement.file, line = statement.line, comments = statement.docstring)
+        super
+      end
+
+      def register_docstring(object, docstring = statement.docstring, stmt = statement)
+        super
+      end
+    end
+
+    class StructHandler < Base
+      statement_class(Statements::Struct)
+
+      process do
+        obj = YARD::CodeObjects::ClassObject.new(:root, statement.name)
+        register(obj)
+
+        push_state(namespace: obj) do
+          parser.process(statement.methods)
+        end
+      end
+    end
+
+    class MethodHandler < Base
+      statement_class(Statements::Method)
+
+      process do
+        obj = MethodObject.new(namespace, statement.name, statement.scope)
+        obj.parameters = statement.parameters if statement.parameters
+        register(obj)
+      end
+    end
+  end
+end

data/lib/yard-rustdoc/parser.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module YARD::Parser::Rustdoc
+  class Parser < YARD::Parser::Base
+    # This default constructor does nothing. The subclass is responsible for
+    # storing the source contents and filename if they are required.
+    # @param [String] source the source contents
+    # @param [String] filename the name of the file if from disk
+    def initialize(source, filename)
+      @source = source
+      @rustdoc_json = JSON.parse(@source).fetch("index") do
+        raise "Expected `index` top-level key in Rustdoc json format"
+      end
+      @filename = filename
+      @entries = []
+    end
+
+    # Override inspect instead of dumping the file content because it is huge.
+    def inspect
+      "<#{self.class.name} @filename=#{@filename.inspect}>"
+    end
+
+    # Finds Rust Struct for the current crate marked with @yard and extract all
+    # the marked methods.
+    # @return [Base] this method should return itself
+    def parse
+      @entries = []
+
+      @rustdoc_json.each do |id, entry|
+        next unless relevant_entry?(entry)
+        next unless entry["kind"] == "struct"
+
+        methods = entry
+          .dig("inner", "impls")
+          .flat_map { |impl_id| @rustdoc_json.dig(impl_id, "inner", "items") }
+          .filter_map do |method_id|
+            method_entry = @rustdoc_json.fetch(method_id)
+            next unless relevant_entry?(method_entry)
+
+            Statements::Method.new(method_entry)
+          end
+
+        @entries << Statements::Struct.new(entry, methods)
+      end
+
+      self
+    end
+
+    def tokenize
+      raise "Rustdoc Parser does not tokenize"
+    end
+
+    # This method should be implemented to return a list of semantic tokens
+    # representing the source code to be post-processed. Otherwise the method
+    # should return nil.
+    #
+    # @abstract
+    # @return [Array] a list of semantic tokens representing the source code
+    #   to be post-processed
+    # @return [nil] if no post-processing should be done
+    def enumerator
+      @entries
+    end
+
+    private
+
+    def relevant_entry?(entry)
+      return false unless entry["crate_id"].zero?
+      return false unless entry["docs"]&.include?("@yard")
+
+      true
+    end
+  end
+end

data/lib/yard-rustdoc/statements.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module YARD::Parser::Rustdoc
+  module Statements
+    class Base
+      def initialize(rustdoc)
+        @rustdoc = rustdoc
+        @name = nil
+        @parameters = []
+      end
+
+      def docstring
+        @rustdoc.fetch("docs")
+      end
+
+      def source
+        return if file.nil?
+
+        File.read(file)
+          .lines
+          .slice(line_index_range)
+          .join
+      rescue Errno::ENOENT
+        log.warn("can't read '#{file}', cwd='#{Dir.pwd}'")
+
+        ""
+      end
+
+      def line
+        line_range.first
+      end
+
+      def line_range
+        @rustdoc.dig("span", "begin", 0)...@rustdoc.dig("span", "end", 0)
+      end
+
+      def file
+        @rustdoc.dig("span", "filename")
+      end
+
+      def show
+        @rustdoc.to_s
+      end
+
+      # Not sure what should go here either
+      def comments_hash_flag
+      end
+
+      def comments_range
+      end
+
+      private
+
+      def line_index_range
+        (@rustdoc.dig("span", "begin", 0) - 1)..@rustdoc.dig("span", "end", 0)
+      end
+    end
+
+    class Struct < Base
+      attr_reader(:methods)
+
+      def initialize(rustdoc, methods)
+        super(rustdoc)
+        @methods = methods
+      end
+
+      def name
+        return $1.strip if docstring =~ /^@rename\s*(.+)/
+
+        @rustdoc["attrs"].each do |attr|
+          next unless attr.include?("magnus")
+
+          # Extract class name from magnus attrs that define classes such as:
+          #   - #[magnus::wrap(class = "ClassName")]
+          #   - #[magnus(class = "ClassName")]
+          return $1.strip if attr =~ /class\s*=\s*"([^"]+)"/
+        end
+
+        # Fallback to the struct's name
+        @rustdoc.fetch("name")
+      end
+    end
+
+    class Method < Base
+      def name
+        parse_def!
+
+        @name || @rustdoc.fetch("name")
+      end
+
+      def scope
+        first_arg = @rustdoc.dig("inner", "decl", "inputs", 0, 0)
+        if first_arg == "self"
+          :instance
+        else
+          :class
+        end
+      end
+
+      # Parses the parameters from the @def annotations in the docstring
+      def parameters
+        parse_def!
+
+        @parameters
+      end
+
+      private
+
+      # Extract @def tag from the docstring. Has to be done before we create
+      # the CodeObject in the `handler` because:
+      #   1. The method name can be overriden -- it's too late for that once
+      #   the method code object exists.
+      #   2. The docstring parser runs automatically after the code object is
+      #   created, and emits warning on udnefined `@param`. We need to set the
+      #   method's parameters before then.
+      def parse_def!
+        return if defined?(@def_parsed)
+        @def_parsed = true
+
+        parsed = YARD::DocstringParser.new.parse(@rustdoc.fetch("docs"))
+        def_tag = parsed.tags.find do |tag|
+          tag.respond_to?(:tag_name) && tag.tag_name == "def"
+        end
+
+        return unless def_tag
+
+        parser = YARD::Rustdoc::DefParser.new(def_tag.text)
+        @name = parser.name
+        @parameters = parser.parameters || []
+      end
+    end
+  end
+end

data/lib/yard-rustdoc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module YARD
+  module Rustdoc
+    VERSION = "0.1.0"
+  end
+end

data/lib/yard-rustdoc.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "json"
+require "yard"
+
+require_relative "yard-rustdoc/version"
+require_relative "yard-rustdoc/parser"
+require_relative "yard-rustdoc/statements"
+require_relative "yard-rustdoc/handlers"
+require_relative "yard-rustdoc/def_parser"
+
+module YARD
+  Parser::SourceParser.register_parser_type(:rustdoc, Parser::Rustdoc::Parser, "json")
+  Handlers::Processor.register_handler_namespace(:rustdoc, Handlers::Rustdoc)
+  Tags::Library.define_tag("Tagging docblock for yard", :yard)
+  Tags::Library.define_tag("Renaming class & methods", :rename)
+  Tags::Library.define_tag("Specify a method name and args", :def)
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: yard-rustdoc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jimmy Bourassa
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: syntax_tree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+description:
+email:
+- jbourassa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/yard-rustdoc.rb
+- lib/yard-rustdoc/def_parser.rb
+- lib/yard-rustdoc/handlers.rb
+- lib/yard-rustdoc/parser.rb
+- lib/yard-rustdoc/statements.rb
+- lib/yard-rustdoc/version.rb
+homepage: https://github.com/oxidize-rb/yard-rustdoc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/oxidize-rb/yard-rustdoc
+  source_code_uri: https://github.com/oxidize-rb/yard-rustdoc
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Generate YARD documentation for Magnus-based Rust gems.
+test_files: []