Improved documentation generation.

21GramConsulting · Mar 22, 2022 · 539fb18 · 539fb18
1 parent 3b579e6
commit 539fb18
Show file tree

Hide file tree

Showing 4 changed files with 98 additions and 77 deletions.
diff --git a/Sources/MediaType/MediaType.swift b/Sources/MediaType/MediaType.swift
@@ -33,67 +33,67 @@ import Foundation
 /// ```
 public enum MediaType {
   /// Represents the `application` media type.
-  ///
+  /// 
   /// Represents binary data. Common examples: `application/json`, `application/octet-stream`.
-  ///
+  /// 
   /// For the whole family of `application` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#application) documentation.
   case application(Application)
   /// Represents the `audio` media type.
-  ///
+  /// 
   /// Represents audible data. Common examples: `audio/ac3`, `audio/mpeg`.
-  ///
+  /// 
   /// For the whole family of `audio` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#audio) documentation.
   case audio(Audio)
   /// Represents the `font` media type.
-  ///
+  /// 
   /// Represents font or typeface data. Common examples: `font/woff`, `font/ttf`.
-  ///
+  /// 
   /// For the whole family of `font` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#font) documentation.
   case font(Font)
   /// Represents the `image` media type.
-  ///
+  /// 
   /// Represents image or graphical data. This includes bitmap and vector images, along with animated image formats.
   /// Common examples: `image/jpeg`, `image/apng`.
-  ///
+  /// 
   /// For the whole family of `image` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#image) documentation.
   case image(Image)
   /// Represents the `message` media type.
-  ///
+  /// 
   /// Represents embedded message data. Common examples: `message/rfc882`, `message/http`.
-  ///
+  /// 
   /// For the whole family of `message` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#message) documentation.
   case message(Message)
   /// Represents the `model` media type.
-  ///
+  /// 
   /// Represents 3D modelling data. Common examples: `model/step`, `model/3mf`.
-  ///
+  /// 
   /// For the whole family of `model` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#model) documentation.
   case model(Model)
   /// Represents the `multipart` media type.
-  ///
+  /// 
   /// Represents data formed from multiple components, which may have their individual media types.
   /// Common examples: `multipart/form-data`, `multipart/encrypted`.
-  ///
+  /// 
   /// For the whole family of `multipart` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#multipart) documentation.
   case multipart(Multipart)
   /// Represents the `text` media type.
-  ///
+  /// 
   /// Represents textual only data. Common examples: `text/css`, `text/html`.
-  ///
+  /// 
   /// For the whole family of `text` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#text) documentation.
   case text(Text)
   /// Represents the `video` media type.
-  ///
+  /// 
   /// Represents video data. Common examples: `video/mp4`, `video/H264`.
-  ///
+  /// 
   /// For the whole family of `video` media types consult the
   /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#video) documentation.
   case video(Video)

diff --git a/UtilityScripts/MediaDocumentations.mjs b/UtilityScripts/MediaDocumentations.mjs
@@ -1,76 +1,97 @@
+/**
+ * @param {[string]} lines
+ * @param {number} indentation
+ * @returns {string}
+ */
+export function toDocumentation(lines, indentation) {
+    return lines
+        .map(line => `/// ${line}`)
+        .map(line => line.padStart(line.length + indentation, ' '))
+        .join('\n')
+}
+
 export const mediaDocumentations = {
     application: {
-        caseDoc: `  /// Represents the \`application\` media type.
-  ///
-  /// Represents binary data. Common examples: \`application/json\`, \`application/octet-stream\`.
-  ///
-  /// For the whole family of \`application\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#application) documentation.`
+        caseDoc: ["Represents the `application` media type.",
+            "",
+            "Represents binary data. Common examples: `application/json`, `application/octet-stream`.",
+            "",
+            "For the whole family of `application` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#application) documentation."
+        ]
     },
     audio: {
-        caseDoc: `  /// Represents the \`audio\` media type.
-  ///
-  /// Represents audible data. Common examples: \`audio/ac3\`, \`audio/mpeg\`.
-  ///
-  /// For the whole family of \`audio\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#audio) documentation.`
+        caseDoc: ["Represents the `audio` media type.",
+            "",
+            "Represents audible data. Common examples: `audio/ac3`, `audio/mpeg`.",
+            "",
+            "For the whole family of `audio` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#audio) documentation."
+        ]
     },
     font: {
-        caseDoc: `  /// Represents the \`font\` media type.
-  ///
-  /// Represents font or typeface data. Common examples: \`font/woff\`, \`font/ttf\`.
-  ///
-  /// For the whole family of \`font\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#font) documentation.`
+        caseDoc: ["Represents the `font` media type.",
+            "",
+            "Represents font or typeface data. Common examples: `font/woff`, `font/ttf`.",
+            "",
+            "For the whole family of `font` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#font) documentation."
+        ]
     },
     image: {
-        caseDoc: `  /// Represents the \`image\` media type.
-  ///
-  /// Represents image or graphical data. This includes bitmap and vector images, along with animated image formats.
-  /// Common examples: \`image/jpeg\`, \`image/apng\`.
-  ///
-  /// For the whole family of \`image\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#image) documentation.`
+        caseDoc: ["Represents the `image` media type.",
+            "",
+            "Represents image or graphical data. This includes bitmap and vector images, along with animated image formats.",
+            "Common examples: `image/jpeg`, `image/apng`.",
+            "",
+            "For the whole family of `image` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#image) documentation."
+        ]
     },
     message: {
-        caseDoc: `  /// Represents the \`message\` media type.
-  ///
-  /// Represents embedded message data. Common examples: \`message/rfc882\`, \`message/http\`.
-  ///
-  /// For the whole family of \`message\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#message) documentation.`
+        caseDoc: ["Represents the `message` media type.",
+            "",
+            "Represents embedded message data. Common examples: `message/rfc882`, `message/http`.",
+            "",
+            "For the whole family of `message` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#message) documentation."
+        ]
     },
     model: {
-        caseDoc: `  /// Represents the \`model\` media type.
-  ///
-  /// Represents 3D modelling data. Common examples: \`model/step\`, \`model/3mf\`.
-  ///
-  /// For the whole family of \`model\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#model) documentation.`
+        caseDoc: ["Represents the `model` media type.",
+            "",
+            "Represents 3D modelling data. Common examples: `model/step`, `model/3mf`.",
+            "",
+            "For the whole family of `model` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#model) documentation."
+        ]
     },
     multipart: {
-        caseDoc: `  /// Represents the \`multipart\` media type.
-  ///
-  /// Represents data formed from multiple components, which may have their individual media types.
-  /// Common examples: \`multipart/form-data\`, \`multipart/encrypted\`.
-  ///
-  /// For the whole family of \`multipart\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#multipart) documentation.`
+        caseDoc: ["Represents the `multipart` media type.",
+            "",
+            "Represents data formed from multiple components, which may have their individual media types.",
+            "Common examples: `multipart/form-data`, `multipart/encrypted`.",
+            "",
+            "For the whole family of `multipart` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#multipart) documentation."
+        ]
     },
     text: {
-        caseDoc: `  /// Represents the \`text\` media type.
-  ///
-  /// Represents textual only data. Common examples: \`text/css\`, \`text/html\`.
-  ///
-  /// For the whole family of \`text\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#text) documentation.`
+        caseDoc: ["Represents the `text` media type.",
+            "",
+            "Represents textual only data. Common examples: `text/css`, `text/html`.",
+            "",
+            "For the whole family of `text` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#text) documentation."
+        ]
     },
     video: {
-        caseDoc: `  /// Represents the \`video\` media type.
-  ///
-  /// Represents video data. Common examples: \`video/mp4\`, \`video/H264\`.
-  ///
-  /// For the whole family of \`video\` media types consult the
-  /// [official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#video) documentation.`
+        caseDoc: ["Represents the `video` media type.",
+            "",
+            "Represents video data. Common examples: `video/mp4`, `video/H264`.",
+            "",
+            "For the whole family of `video` media types consult the",
+            "[official IANA](https://www.iana.org/assignments/media-types/media-types.xhtml#video) documentation."
+        ]
     }
 }
diff --git a/UtilityScripts/SubtypeEnumGenerator.mjs b/UtilityScripts/SubtypeEnumGenerator.mjs
@@ -2,7 +2,7 @@
 
 import {readFileSync, writeFileSync} from 'fs';
 import {toFormattedSwitchCase} from './commonUtility.mjs';
-import {mediaDocumentations} from './MediaDocumentations.mjs';
+import {mediaDocumentations, toDocumentation} from './MediaDocumentations.mjs';
 
 String.prototype.snakeToCamel = function () {
     return this.replace(/-(.)/g, (_, m) => m.toUpperCase())
@@ -270,7 +270,7 @@ writeFileSync(
 public enum MediaType {
 ${
         types
-            .map(({lowerCase, pascalCase}) => `${mediaDocumentations[lowerCase].caseDoc}
+            .map(({lowerCase, pascalCase}) => `${toDocumentation(mediaDocumentations[lowerCase].caseDoc, 2)}
   case ${lowerCase}(${pascalCase})`)
             .join('\n')
     }

diff --git a/UtilityScripts/commonUtility.mjs b/UtilityScripts/commonUtility.mjs
@@ -7,4 +7,4 @@ export const toFormattedSwitchCase = ([caseColumn, returnColumn], _, l) => caseC
             .length - caseColumn.length
         ).fill(" ").join("")
     )
-    .concat(returnColumn);
+    .concat(returnColumn);