feat(graindoc): Support deprecations on module docblocks (#1498)

chore(stdlib): Deprecate Stack & Queue modules
chore(stdlib): Regenerate markdown docs for Stack & Queue modules

Author: phated

compiler/graindoc/graindoc.re

@@ -87,12 +87,37 @@ let generate_docs =
   let module_name = ref(None);
   switch (module_comment) {
   | Some((_, desc, attrs)) =>
+    let deprecations =
+      attrs
+      |> List.filter(Comments.Attribute.is_deprecated)
+      |> List.map((attr: Comments.Attribute.t) => {
+           switch (attr) {
+           | Deprecated({attr_desc}) => attr_desc
+           | _ =>
+             failwith(
+               "Unreachable: Non-`deprecated` attribute can't exist here.",
+             )
+           }
+         });
+
     // TODO(#787): Should we fail if more than one `@module` attribute?
     let module_attr = attrs |> List.find(Comments.Attribute.is_module);
     switch (module_attr) {
     | Module({attr_name, attr_desc}) =>
       module_name := Some(attr_name);
       Buffer.add_string(buf, Markdown.frontmatter([("title", attr_name)]));
+      if (List.length(deprecations) > 0) {
+        List.iter(
+          msg =>
+            Buffer.add_string(
+              buf,
+              Markdown.blockquote(
+                Markdown.bold("Deprecated:") ++ " " ++ msg,
+              ),
+            ),
+          deprecations,
+        );
+      };
       Buffer.add_string(buf, Markdown.paragraph(attr_desc));
       switch (desc) {
       // Guard isn't be needed because we turn an empty string into None during extraction

stdlib/queue.gr

@@ -2,6 +2,8 @@
  * @module Queue: An immutable queue implementation. A queue is a FIFO (first-in-first-out) data structure where new values are added to the end and retrieved or removed from the beginning.
  * @example import Queue from "queue"
  * @since v0.2.0
+ *
+ * @deprecated This module will be renamed to ImmutableQueue in the v0.6.0 release of Grain.
  */
 import List from "list"
 
@@ -20,7 +22,7 @@ record Queue<a> {
 
 /**
  * An empty queue.
- * 
+ *
  * @since v0.5.4
  */
 export let empty = {
@@ -30,11 +32,11 @@ export let empty = {
 
 /**
  * Creates an empty queue.
- * 
+ *
  * @returns An empty queue
- * 
+ *
  * @deprecated This will be removed in the v0.6.0 release of Grain.
- * 
+ *
  * @since v0.2.0
  */
 export let make = () => {
@@ -43,7 +45,7 @@ export let make = () => {
 
 /**
  * Checks if the given queue contains any values.
- * 
+ *
  * @param queue: The queue to check
  * @returns `true` if the given queue is empty or `false` otherwise
  *
@@ -58,7 +60,7 @@ export let isEmpty = queue => {
 
 /**
  * Returns the value at the beginning of the queue. It is not removed from the queue.
- * 
+ *
  * @param queue: The queue to inspect
  * @returns `Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty
  *
@@ -76,7 +78,7 @@ export let peek = queue => {
 
 /**
  * Adds a value to the end of the queue.
- * 
+ *
  * @param value: The value to append
  * @param queue: The queue to update
  * @returns An updated queue
@@ -95,7 +97,7 @@ export let push = (value, queue) => {
 
 /**
  * Dequeues the next value in the queue.
- * 
+ *
  * @param queue: The queue to change
  * @returns An updated queue
  *
@@ -119,7 +121,7 @@ export let pop = queue => {
 
 /**
  * Get the number of values in a queue.
- * 
+ *
  * @param queue: The queue to inspect
  * @returns The number of values in the queue
  *

stdlib/queue.md

@@ -2,6 +2,8 @@
 title: Queue
 ---
 
+> **Deprecated:** This module will be renamed to ImmutableQueue in the v0.6.0 release of Grain.
+
 An immutable queue implementation. A queue is a FIFO (first-in-first-out) data structure where new values are added to the end and retrieved or removed from the beginning.
 
 <details disabled>

stdlib/stack.gr

@@ -1,6 +1,8 @@
 /**
  * @module Stack: An immutable stack implementation. A stack is a LIFO (last-in-first-out) data structure where new values are added, retrieved, and removed from the end.
  * @example import Stack from "stack"
+ *
+ * @deprecated This module will be renamed to ImmutableStack in the v0.6.0 release of Grain.
  */
 
 import List from "list"
@@ -22,7 +24,7 @@ record Stack<a> {
 
 /**
  * An empty stack.
- * 
+ *
  * @since v0.5.4
  */
 export let empty = {
@@ -34,7 +36,7 @@ export let empty = {
  * Creates a new stack.
  *
  * @returns An empty stack
- * 
+ *
  * @deprecated This will be removed in the v0.6.0 release of Grain.
  */
 export let make = () => {

stdlib/stack.md

@@ -2,6 +2,8 @@
 title: Stack
 ---
 
+> **Deprecated:** This module will be renamed to ImmutableStack in the v0.6.0 release of Grain.
+
 An immutable stack implementation. A stack is a LIFO (last-in-first-out) data structure where new values are added, retrieved, and removed from the end.
 
 ```grain