[ruby/prism] More docs improvements

(ruby/prism#3910)

* Update C call seqs

* Prefixing them with self is unusual
* Also use `.` instead of `::` to refer to class methods

* Capitalize location in docs

It allows it to be linked to in docs

* Miscelanous other doc tweaks

* Format code as code
* Nodoc some missed methods
* Fix method reference

* Really try to nodoc ffi module

The previous approach was wrong, to nodoc the class methods
it must be specified at the module itself.
As a result, the private methods like `dump_options` are also removed.

* Remove some def-style comments

They are mostly redundant with the method signature and don't look great when rendered.

Still remaining on nodes. I will improve docs for them in a separate PR

ruby/prism@94e5525521

Author: Earlopain

lib/prism.rb

@@ -56,18 +56,18 @@ def initialize(version)
   end
 
   # :call-seq:
-  #   Prism::lex_compat(source, **options) -> LexCompat::Result
+  #   lex_compat(source, **options) -> LexCompat::Result
   #
   # Returns a parse result whose value is an array of tokens that closely
-  # resembles the return value of Ripper::lex.
+  # resembles the return value of Ripper.lex.
   #
-  # For supported options, see Prism::parse.
+  # For supported options, see Prism.parse.
   def self.lex_compat(source, **options)
     LexCompat.new(source, **options).result # steep:ignore
   end
 
   # :call-seq:
-  #   Prism::load(source, serialized, freeze) -> ParseResult
+  #   load(source, serialized, freeze) -> ParseResult
   #
   # Load the serialized AST using the source as a reference into a tree.
   def self.load(source, serialized, freeze = false)

lib/prism/desugar_compiler.rb

@@ -254,137 +254,137 @@ def desugar # :nodoc:
   # DesugarCompiler is a compiler that desugars Ruby code into a more primitive
   # form. This is useful for consumers that want to deal with fewer node types.
   class DesugarCompiler < MutationCompiler
-    # @@foo &&= bar
+    # `@@foo &&= bar`
     #
     # becomes
     #
-    # @@foo && @@foo = bar
+    # `@@foo && @@foo = bar`
     def visit_class_variable_and_write_node(node)
       node.desugar
     end
 
-    # @@foo ||= bar
+    # `@@foo ||= bar`
     #
     # becomes
     #
-    # defined?(@@foo) ? @@foo : @@foo = bar
+    # `defined?(@@foo) ? @@foo : @@foo = bar`
     def visit_class_variable_or_write_node(node)
       node.desugar
     end
 
-    # @@foo += bar
+    # `@@foo += bar`
     #
     # becomes
     #
-    # @@foo = @@foo + bar
+    # `@@foo = @@foo + bar`
     def visit_class_variable_operator_write_node(node)
       node.desugar
     end
 
-    # Foo &&= bar
+    # `Foo &&= bar`
     #
     # becomes
     #
-    # Foo && Foo = bar
+    # `Foo && Foo = bar`
     def visit_constant_and_write_node(node)
       node.desugar
     end
 
-    # Foo ||= bar
+    # `Foo ||= bar`
     #
     # becomes
     #
-    # defined?(Foo) ? Foo : Foo = bar
+    # `defined?(Foo) ? Foo : Foo = bar`
     def visit_constant_or_write_node(node)
       node.desugar
     end
 
-    # Foo += bar
+    # `Foo += bar`
     #
     # becomes
     #
-    # Foo = Foo + bar
+    # `Foo = Foo + bar`
     def visit_constant_operator_write_node(node)
       node.desugar
     end
 
-    # $foo &&= bar
+    # `$foo &&= bar`
     #
     # becomes
     #
-    # $foo && $foo = bar
+    # `$foo && $foo = bar`
     def visit_global_variable_and_write_node(node)
       node.desugar
     end
 
-    # $foo ||= bar
+    # `$foo ||= bar`
     #
     # becomes
     #
-    # defined?($foo) ? $foo : $foo = bar
+    # `defined?($foo) ? $foo : $foo = bar`
     def visit_global_variable_or_write_node(node)
       node.desugar
     end
 
-    # $foo += bar
+    # `$foo += bar`
     #
     # becomes
     #
-    # $foo = $foo + bar
+    # `$foo = $foo + bar`
     def visit_global_variable_operator_write_node(node)
       node.desugar
     end
 
-    # @foo &&= bar
+    # `@foo &&= bar`
     #
     # becomes
     #
-    # @foo && @foo = bar
+    # `@foo && @foo = bar`
     def visit_instance_variable_and_write_node(node)
       node.desugar
     end
 
-    # @foo ||= bar
+    # `@foo ||= bar`
     #
     # becomes
     #
-    # @foo || @foo = bar
+    # `@foo || @foo = bar`
     def visit_instance_variable_or_write_node(node)
       node.desugar
     end
 
-    # @foo += bar
+    # `@foo += bar`
     #
     # becomes
     #
-    # @foo = @foo + bar
+    # `@foo = @foo + bar`
     def visit_instance_variable_operator_write_node(node)
       node.desugar
     end
 
-    # foo &&= bar
+    # `foo &&= bar`
     #
     # becomes
     #
-    # foo && foo = bar
+    # `foo && foo = bar`
     def visit_local_variable_and_write_node(node)
       node.desugar
     end
 
-    # foo ||= bar
+    # `foo ||= bar`
     #
     # becomes
     #
-    # foo || foo = bar
+    # `foo || foo = bar`
     def visit_local_variable_or_write_node(node)
       node.desugar
     end
 
-    # foo += bar
+    # `foo += bar`
     #
     # becomes
     #
-    # foo = foo + bar
+    # `foo = foo + bar`
     def visit_local_variable_operator_write_node(node)
       node.desugar
     end

lib/prism/ffi.rb

@@ -12,7 +12,7 @@
 # autoloaded from within a non-main Ractor.
 require "prism/serialize" if defined?(Ractor)
 
-module Prism
+module Prism # :nodoc:
   module LibRubyParser # :nodoc:
     extend FFI::Library
 
@@ -233,7 +233,7 @@ def self.with_file(filepath)
   # The version constant is set by reading the result of calling pm_version.
   VERSION = LibRubyParser.pm_version.read_string.freeze
 
-  class << self # :nodoc:
+  class << self
     # Mirror the Prism.dump API by using the serialization API.
     def dump(source, **options)
       LibRubyParser::PrismString.with_string(source) { |string| dump_common(string, options) }

lib/prism/parse_result.rb

@@ -519,7 +519,7 @@ def adjoin(string)
   # This represents a comment that was encountered during parsing. It is the
   # base class for all comment types.
   class Comment
-    # The location of this comment in the source.
+    # The Location of this comment in the source.
     attr_reader :location
 
     # Create a new comment object with the given location.
@@ -556,7 +556,7 @@ def inspect # :nodoc:
   # EmbDocComment objects correspond to comments that are surrounded by =begin
   # and =end.
   class EmbDocComment < Comment
-    # This can only be true for inline comments.
+    # Returns false. This can only be true for inline comments.
     def trailing?
       false
     end
@@ -670,9 +670,9 @@ def inspect # :nodoc:
     end
   end
 
-  # This represents the result of a call to ::parse or ::parse_file. It contains
-  # the requested structure, any comments that were encounters, and any errors
-  # that were encountered.
+  # This represents the result of a call to Prism.parse or Prism.parse_file.
+  # It contains the requested structure, any comments that were encounters,
+  # and any errors that were encountered.
   class Result
     # The list of comments that were encountered during parsing.
     attr_reader :comments

lib/prism/pattern.rb

@@ -41,7 +41,7 @@ class Pattern
     class CompilationError < StandardError
       # Create a new CompilationError with the given representation of the node
       # that caused the error.
-      def initialize(repr)
+      def initialize(repr) # :nodoc:
         super(<<~ERROR)
           prism was unable to compile the pattern you provided into a usable
           expression. It failed on to understand the node represented by:

prism/api_pack.c

@@ -173,7 +173,7 @@ pack_encoding_to_ruby(pm_pack_encoding encoding) {
 
 /**
  * call-seq:
- *   Pack::parse(version, variant, source) -> Format
+ *   parse(version, variant, source) -> Format
  *
  * Parse the given source and return a format object.
  */