Last remaining missing C comments

Doxyfile

@@ -24,16 +24,15 @@ PROJECT_NAME           = "Prism"
 OUTPUT_DIRECTORY       = doc
 JAVADOC_AUTOBRIEF      = YES
 OPTIMIZE_OUTPUT_FOR_C  = YES
-EXTRACT_ALL            = YES
 INPUT                  = src src/enc src/util include include/prism include/prism/enc include/prism/util
 HTML_OUTPUT            = c
+WARN_IF_UNDOCUMENTED   = YES
+WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = FAIL_ON_WARNINGS
+WARN_IF_UNDOC_ENUM_VAL = YES
+SORT_MEMBER_DOCS       = NO
 
 # Default options we might want to edit in the future
 HTML_STYLESHEET        =
 HTML_COLORSTYLE        = AUTO_LIGHT
 GENERATE_LATEX         = NO
-
-# Default options we definitely want to edit in the future
-WARN_IF_UNDOCUMENTED   = NO
-WARN_NO_PARAMDOC       = NO
-WARN_AS_ERROR          = NO

config.yml

@@ -59,11 +59,11 @@ tokens:
   - name: CONSTANT
     comment: "a constant"
   - name: DOT
-    comment: "."
+    comment: "the . call operator"
   - name: DOT_DOT
-    comment: ".."
+    comment: "the .. range operator"
   - name: DOT_DOT_DOT
-    comment: "..."
+    comment: "the ... range operator or forwarding parameter"
   - name: EMBDOC_BEGIN
     comment: "=begin"
   - name: EMBDOC_END
@@ -311,9 +311,9 @@ tokens:
   - name: UCOLON_COLON
     comment: "unary ::"
   - name: UDOT_DOT
-    comment: "unary .."
+    comment: "unary .. operator"
   - name: UDOT_DOT_DOT
-    comment: "unary ..."
+    comment: "unary ... operator"
   - name: UMINUS
     comment: "-@"
   - name: UMINUS_NUM

include/prism.h

@@ -1,3 +1,8 @@
+/**
+ * @file prism.h
+ *
+ * The main header file for the prism parser.
+ */
 #ifndef PRISM_H
 #define PRISM_H
 
@@ -75,10 +80,10 @@ PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_decode_callback(pm_pars
 PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser);
 
 /**
- * Parse the Ruby source associated with the given parser and return the tree.
+ * Initiate the parser with the given parser.
  *
  * @param parser The parser to use.
- * @return The AST representing the Ruby source.
+ * @return The AST representing the source.
  */
 PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse(pm_parser_t *parser);
 
@@ -181,4 +186,103 @@ PRISM_EXPORTED_FUNCTION void pm_parse_lex_serialize(const uint8_t *source, size_
  */
 PRISM_EXPORTED_FUNCTION const char * pm_token_type_to_str(pm_token_type_t token_type);
 
+/**
+ * @mainpage
+ *
+ * Prism is a parser for the Ruby programming language. It is designed to be
+ * portable, error tolerant, and maintainable. It is written in C99 and has no
+ * dependencies. It is currently being integrated into
+ * [CRuby](https://github.com/ruby/ruby),
+ * [JRuby](https://github.com/jruby/jruby),
+ * [TruffleRuby](https://github.com/oracle/truffleruby),
+ * [Sorbet](https://github.com/sorbet/sorbet), and
+ * [Syntax Tree](https://github.com/ruby-syntax-tree/syntax_tree).
+ *
+ * @section getting-started Getting started
+ *
+ * If you're vendoring this project and compiling it statically then as long as
+ * you have a C99 compiler you will be fine. If you're linking against it as
+ * shared library, then you should compile with `-fvisibility=hidden` and
+ * `-DPRISM_EXPORT_SYMBOLS` to tell prism to make only its public interface
+ * visible.
+ *
+ * @section parsing Parsing
+ * 
+ * In order to parse Ruby code, the structures and functions that you're going
+ * to want to use and be aware of are:
+ *
+ * * pm_parser_t - the main parser structure
+ * * pm_parser_init - initialize a parser
+ * * pm_parse - parse and return the root node
+ * * pm_node_destroy - deallocate the root node returned by `pm_parse`
+ * * pm_parser_free - free the internal memory of the parser
+ *
+ * Putting all of this together would look something like:
+ *
+ * ```c
+ * void parse(const uint8_t *source, size_t length) {
+ *     pm_parser_t parser;
+ *     pm_parser_init(&parser, source, length, NULL);
+ *
+ *     pm_node_t *root = pm_parse(&parser);
+ *     printf("PARSED!\n");
+ *
+ *     pm_node_destroy(root);
+ *     pm_parser_free(&parser);
+ * }
+ * ```
+ *
+ * All of the nodes "inherit" from `pm_node_t` by embedding those structures as
+ * their first member. This means you can downcast and upcast any node in the
+ * tree to a `pm_node_t`.
+ *
+ * @section serializing Serializing
+ *
+ * Prism provides the ability to serialize the AST and its related metadata into
+ * a binary format. This format is designed to be portable to different
+ * languages and runtimes so that you only need to make one FFI call in order to
+ * parse Ruby code. The structures and functions that you're going to want to
+ * use and be aware of are:
+ *
+ * * pm_buffer_t - a small buffer object that will hold the serialized AST
+ * * pm_buffer_free - free the memory associated with the buffer
+ * * pm_serialize - serialize the AST into a buffer
+ * * pm_parse_serialize - parse and serialize the AST into a buffer
+ *
+ * Putting all of this together would look something like:
+ *
+ * ```c
+ * void serialize(const uint8_t *source, size_t length) {
+ *     pm_buffer_t buffer = { 0 };
+ *
+ *     pm_parse_serialize(source, length, &buffer, NULL);
+ *     printf("SERIALIZED!\n");
+ *
+ *     pm_buffer_free(&buffer);
+ * }
+ * ```
+ *
+ * @section inspecting Inspecting
+ *
+ * Prism provides the ability to inspect the AST by pretty-printing nodes. You
+ * can do this with the `pm_prettyprint` function, which you would use like:
+ *
+ * ```c
+ * void prettyprint(const uint8_t *source, size_t length) {
+ *     pm_parser_t parser;
+ *     pm_parser_init(&parser, source, length, NULL);
+ *
+ *     pm_node_t *root = pm_parse(&parser);
+ *     pm_buffer_t buffer = { 0 };
+ *
+ *     pm_prettyprint(&buffer, &parser, root);
+ *     printf("*.s%\n", (int) buffer.length, buffer.value);
+ *
+ *     pm_buffer_free(&buffer);
+ *     pm_node_destroy(root);
+ *     pm_parser_free(&parser);
+ * }
+ * ```
+ */
+
 #endif

include/prism/defines.h

@@ -1,16 +1,26 @@
+/**
+ * @file defines.h
+ *
+ * Macro definitions used throughout the prism library.
+ *
+ * This file should be included first by any *.h or *.c in prism for consistency
+ * and to ensure that the macros are defined before they are used.
+ */
 #ifndef PRISM_DEFINES_H
 #define PRISM_DEFINES_H
 
-// This file should be included first by any *.h or *.c in prism.
-
 #include <ctype.h>
 #include <stdarg.h>
 #include <stddef.h>
 #include <stdint.h>
 #include <stdio.h>
 #include <string.h>
 
-// PRISM_EXPORTED_FUNCTION
+/** 
+ * By default, we compile with -fvisibility=hidden. When this is enabled, we
+ * need to mark certain functions as being publically-visible. This macro does
+ * that in a compiler-agnostic way.
+ */
 #ifndef PRISM_EXPORTED_FUNCTION
 #   ifdef PRISM_EXPORT_SYMBOLS
 #       ifdef _WIN32
@@ -23,7 +33,12 @@
 #   endif
 #endif
 
-// PRISM_ATTRIBUTE_FORMAT
+/**
+ * Certain compilers support specifying that a function accepts variadic
+ * parameters that look like printf format strings to provide a better developer
+ * experience when someone is using the function. This macro does that in a
+ * compiler-agnostic way.
+ */
 #if defined(__GNUC__)
 #   define PRISM_ATTRIBUTE_FORMAT(string_index, argument_index) __attribute__((format(printf, string_index, argument_index)))
 #elif defined(__clang__)
@@ -32,19 +47,29 @@
 #   define PRISM_ATTRIBUTE_FORMAT(string_index, argument_index)
 #endif
 
-// PRISM_ATTRIBUTE_UNUSED
+/**
+ * GCC will warn if you specify a function or parameter that is unused at
+ * runtime. This macro allows you to mark a function or parameter as unused in a
+ * compiler-agnostic way.
+ */
 #if defined(__GNUC__)
 #   define PRISM_ATTRIBUTE_UNUSED __attribute__((unused))
 #else
 #   define PRISM_ATTRIBUTE_UNUSED
 #endif
 
-// inline
+/**
+ * Old Visual Studio versions do not support the inline keyword, so we need to
+ * define it to be __inline.
+ */
 #if defined(_MSC_VER) && !defined(inline)
 #   define inline __inline
 #endif
 
-// Windows versions before 2015 use _snprintf
+/**
+ * Old Visual Studio versions before 2015 do not implement sprintf, but instead
+ * implement _snprintf. We standard that here.
+ */
 #if !defined(snprintf) && defined(_MSC_VER) && (_MSC_VER < 1900)
 #   define snprintf _snprintf
 #endif

include/prism/diagnostic.h

@@ -1,3 +1,8 @@
+/**
+ * @file diagnostic.h
+ *
+ * A list of diagnostics generated during parsing.
+ */
 #ifndef PRISM_DIAGNOSTIC_H
 #define PRISM_DIAGNOSTIC_H
 
@@ -9,14 +14,21 @@
 #include <assert.h>
 
 /**
- * This struct represents a diagnostic found during parsing.
+ * This struct represents a diagnostic generated during parsing.
  *
  * @extends pm_list_node_t
  */
 typedef struct {
+    /** The embedded base node. */
     pm_list_node_t node;
+
+    /** A pointer to the start of the source that generated the diagnostic. */
     const uint8_t *start;
+
+    /** A pointer to the end of the source that generated the diagnostic. */
     const uint8_t *end;
+
+    /** The message associated with the diagnostic. */
     const char *message;
 } pm_diagnostic_t;
 

include/prism/enc/pm_encoding.h

@@ -1,3 +1,8 @@
+/**
+ * @file pm_encoding.h
+ *
+ * The encoding interface and implementations used by the parser.
+ */
 #ifndef PRISM_ENCODING_H
 #define PRISM_ENCODING_H
 
@@ -55,10 +60,22 @@ typedef struct {
     bool multibyte;
 } pm_encoding_t;
 
-// These bits define the location of each bit of metadata within the various
-// lookup tables that are used to determine the properties of a character.
+/**
+ * All of the lookup tables use the first bit of each embedded byte to indicate
+ * whether the codepoint is alphabetical.
+ */
 #define PRISM_ENCODING_ALPHABETIC_BIT 1 << 0
+
+/**
+ * All of the lookup tables use the second bit of each embedded byte to indicate
+ * whether the codepoint is alphanumeric.
+ */
 #define PRISM_ENCODING_ALPHANUMERIC_BIT 1 << 1
+
+/**
+ * All of the lookup tables use the third bit of each embedded byte to indicate
+ * whether the codepoint is uppercase.
+ */
 #define PRISM_ENCODING_UPPERCASE_BIT 1 << 2
 
 /**

include/prism/node.h

@@ -1,3 +1,8 @@
+/**
+ * @file node.h
+ *
+ * Functions related to nodes in the AST.
+ */
 #ifndef PRISM_NODE_H
 #define PRISM_NODE_H