prism 0.16.0 → 0.17.0

data/src/diagnostic.c

@@ -1,56 +1,55 @@
 #include "prism/diagnostic.h"
 
-/*
-  ## Message composition
-
-  When composing an error message, use sentence fragments.
-
-  Try describing the property of the code that caused the error, rather than the rule that is being
-  violated. It may help to use a fragment that completes a sentence beginning, "The parser
-  encountered (a) ...". If appropriate, add a description of the rule violation (or other helpful
-  context) after a semicolon.
-
-  For example:, instead of "Control escape sequence cannot be doubled", prefer:
-
-  > "Invalid control escape sequence; control cannot be repeated"
-
-  In some cases, where the failure is more general or syntax expectations are violated, it may make
-  more sense to use a fragment that completes a sentence beginning, "The parser ...".
-
-  For example:
-
-  > "Expected an expression after `(`"
-  > "Cannot parse the expression"
-
-
-  ## Message style guide
-
-  - Use articles like "a", "an", and "the" when appropriate.
-    - e.g., prefer "Cannot parse the expression" to "Cannot parse expression".
-  - Use the common name for tokens and nodes.
-    - e.g., prefer "keyword splat" to "assoc splat"
-    - e.g., prefer "embedded document" to "embdoc"
-  - Capitalize the initial word of the message.
-  - Use back ticks around token literals
-    - e.g., "Expected a `=>` between the hash key and value"
-  - Do not use `.` or other punctuation at the end of the message.
-  - Do not use contractions like "can't". Prefer "cannot" to "can not".
-  - For tokens that can have multiple meanings, reference the token and its meaning.
-    - e.g., "`*` splat argument" is clearer and more complete than "splat argument" or "`*` argument"
-
-
-  ## Error names (PM_ERR_*)
-
-  - When appropriate, prefer node name to token name.
-    - e.g., prefer "SPLAT" to "STAR" in the context of argument parsing.
-  - Prefer token name to common name.
-    - e.g., prefer "STAR" to "ASTERISK".
-  - Try to order the words in the name from more general to more specific,
-    - e.g., "INVALID_NUMBER_DECIMAL" is better than "DECIMAL_INVALID_NUMBER".
-    - When in doubt, look for similar patterns and name them so that they are grouped when lexically
-      sorted. See PM_ERR_ARGUMENT_NO_FORWARDING_* for an example.
-*/
-
+/**
+ * ## Message composition
+ *
+ * When composing an error message, use sentence fragments.
+ *
+ * Try describing the property of the code that caused the error, rather than the rule that is being
+ * violated. It may help to use a fragment that completes a sentence beginning, "The parser
+ * encountered (a) ...". If appropriate, add a description of the rule violation (or other helpful
+ * context) after a semicolon.
+ *
+ * For example:, instead of "Control escape sequence cannot be doubled", prefer:
+ *
+ * > "Invalid control escape sequence; control cannot be repeated"
+ *
+ * In some cases, where the failure is more general or syntax expectations are violated, it may make
+ * more sense to use a fragment that completes a sentence beginning, "The parser ...".
+ *
+ * For example:
+ *
+ * > "Expected an expression after `(`"
+ * > "Cannot parse the expression"
+ *
+ *
+ * ## Message style guide
+ *
+ * - Use articles like "a", "an", and "the" when appropriate.
+ *   - e.g., prefer "Cannot parse the expression" to "Cannot parse expression".
+ * - Use the common name for tokens and nodes.
+ *   - e.g., prefer "keyword splat" to "assoc splat"
+ *   - e.g., prefer "embedded document" to "embdoc"
+ * - Capitalize the initial word of the message.
+ * - Use back ticks around token literals
+ *   - e.g., "Expected a `=>` between the hash key and value"
+ * - Do not use `.` or other punctuation at the end of the message.
+ * - Do not use contractions like "can't". Prefer "cannot" to "can not".
+ * - For tokens that can have multiple meanings, reference the token and its meaning.
+ *   - e.g., "`*` splat argument" is clearer and more complete than "splat argument" or "`*` argument"
+ *
+ *
+ * ## Error names (PM_ERR_*)
+ *
+ * - When appropriate, prefer node name to token name.
+ *   - e.g., prefer "SPLAT" to "STAR" in the context of argument parsing.
+ * - Prefer token name to common name.
+ *   - e.g., prefer "STAR" to "ASTERISK".
+ * - Try to order the words in the name from more general to more specific,
+ *   - e.g., "INVALID_NUMBER_DECIMAL" is better than "DECIMAL_INVALID_NUMBER".
+ *   - When in doubt, look for similar patterns and name them so that they are grouped when lexically
+ *     sorted. See PM_ERR_ARGUMENT_NO_FORWARDING_* for an example.
+ */
 static const char* const diagnostic_messages[PM_DIAGNOSTIC_ID_LEN] = {
     [PM_ERR_ALIAS_ARGUMENT]                     = "Invalid argument being passed to `alias`; expected a bare word, symbol, constant, or global variable",
     [PM_ERR_AMPAMPEQ_MULTI_ASSIGN]              = "Unexpected `&&=` in a multiple assignment",
@@ -263,7 +262,9 @@ pm_diagnostic_message(pm_diagnostic_id_t diag_id) {
     return message;
 }
 
-// Append an error to the given list of diagnostic.
+/**
+ * Append an error to the given list of diagnostic.
+ */
 bool
 pm_diagnostic_list_append(pm_list_t *list, const uint8_t *start, const uint8_t *end, pm_diagnostic_id_t diag_id) {
     pm_diagnostic_t *diagnostic = (pm_diagnostic_t *) calloc(sizeof(pm_diagnostic_t), 1);
@@ -274,7 +275,9 @@ pm_diagnostic_list_append(pm_list_t *list, const uint8_t *start, const uint8_t *
     return true;
 }
 
-// Deallocate the internal state of the given diagnostic list.
+/**
+ * Deallocate the internal state of the given diagnostic list.
+ */
 void
 pm_diagnostic_list_free(pm_list_t *list) {
     pm_list_node_t *node, *next;

data/src/enc/pm_big5.c

@@ -42,6 +42,7 @@ pm_encoding_big5_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** Big5 encoding */
 pm_encoding_t pm_encoding_big5 = {
     .name = "big5",
     .char_width = pm_encoding_big5_char_width,

data/src/enc/pm_euc_jp.c

@@ -48,6 +48,7 @@ pm_encoding_euc_jp_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** EUC-JP encoding */
 pm_encoding_t pm_encoding_euc_jp = {
     .name = "euc-jp",
     .char_width = pm_encoding_euc_jp_char_width,

data/src/enc/pm_gbk.c

@@ -51,6 +51,7 @@ pm_encoding_gbk_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** GBK encoding */
 pm_encoding_t pm_encoding_gbk = {
     .name = "gbk",
     .char_width = pm_encoding_gbk_char_width,

data/src/enc/pm_shift_jis.c

@@ -46,6 +46,7 @@ pm_encoding_shift_jis_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** Shift_JIS encoding */
 pm_encoding_t pm_encoding_shift_jis = {
     .name = "shift_jis",
     .char_width = pm_encoding_shift_jis_char_width,