documentation; naming consistency

Author: eritbh

extension/data/frontends/index.tsx

@@ -1,6 +1,6 @@
 // Defines a system of "slots" which modules can use to render interface
-// elements within the page. Slot locations are standardized for consumers (e.g.
-// a module says it wants to display a button next to comment author usernames)
+// elements within the page. Slot types are standardized for consumers (e.g. a
+// module says it wants to display a button next to comment author usernames)
 // and their actual position in the DOM is controlled by platform-specific
 // observers responding to changes in the page and dynamically creating React
 // roots which this code then populates with the appropriate contents.
@@ -17,124 +17,190 @@ import modmailObserver from './modmail';
 import oldRedditObserver from './oldreddit';
 import shredditObserver from './shreddit';
 
-// NOMERGE: document all of these
+/** Basic information about a subreddit. */
 interface PlatformSlotDetailsSubreddit {
+    /** The subreddit's fullname, beginning with ``. */
     fullname?: string;
+    /** The name of the subreddit */
     name: string;
 }
 
+/** Basic information about a user. */
 export type PlatformSlotDetailsUser = {
+    /** If `true`, this is a deleted user. */
     deleted: true;
 } | {
+    /** If `true`, this is a deleted user. */
     deleted: false;
+    /** The user's fullname, starting with ``. */
     fullname?: string;
+    /** The user's username. */
     name: string;
 };
 
+/** Basic information about a submission. */
 interface PlatformSlotDetailsSubmission {
+    /** The submission's fullname, beginning with ``. */
     fullname: string;
 }
 
+/** Basic information about a comment. */
 interface PlatformSlotDetailsComment {
+    /** The comment's fullname, beginning with ``. */
     fullname: string;
 }
 
 // Slot names and the type of associated contextual information
-// NOMERGE: document
+
+/** Contextual information provided to consumers of each type of slot. */
 export interface PlatformSlotDetails {
+    /** Details for a submission author slot. */
     submissionAuthor: {
+        /** The author of this submission */
         user: PlatformSlotDetailsUser;
+        /** The submission */
         submission?: PlatformSlotDetailsSubmission;
+        /** The subreddit where this submission was posted */
         subreddit: PlatformSlotDetailsSubreddit;
+        // /** The type of distinguish on the submission, if any */
         // distinguishType: null | 'moderator' | 'employee' | 'alumnus';
-        // stickied: boolean;
+        // /** The sticky slot populated by the submission, if any */
+        // stickied: false | 1 | 2;
     };
     commentAuthor: {
+        /** The author of the comment */
         user: PlatformSlotDetailsUser;
+        /** The comment */
         comment: PlatformSlotDetailsComment;
+        /** The parent submission the comment was left under */
         submission?: PlatformSlotDetailsSubmission;
+        /** The subreddit where the comment was posted */
         subreddit: PlatformSlotDetailsSubreddit;
+        // /** The type of distinguish on the comment, if any */
         // distinguished: boolean;
+        // /** Whether the comment is stickied */
         // stickied: boolean;
     };
     modmailAuthor: {
+        /** The author of the message */
         user: PlatformSlotDetailsUser;
+        /** The subreddit that initially received this message's thread */
         subreddit: PlatformSlotDetailsSubreddit;
+        /** The thread this message is in */
         thread: {fullname: string};
+        /** The message */
         message: {fullname: string};
+        // /** Whether the author is a moderator */
         // authorIsModerator: boolean;
+        // /** Whether this message was sent "as the subreddit" (with username hidden) */
         // repliedAsSubreddit: boolean;
     };
     userHovercard: {
+        /** The user */
         user: PlatformSlotDetailsUser;
+        /**
+         * The subreddit of the content the hovercard was triggered from. For
+         * example if the hovercard was triggered from an author name on a
+         * submission, this would be the subreddit it was submitted to; if the
+         * hovercard is triggered on a user in a modmail thread, this would be
+         * the subreddit that received the thread.
+         */
         subreddit: PlatformSlotDetailsSubreddit;
+        /**
+         * The fullname of the submission, comment, modmail thread, etc. the
+         * hovercard was triggered from
+         */
         contextFullname?: string;
     };
 }
-export type PlatformSlotLocation = keyof PlatformSlotDetails;
+/**
+ * A slot type. Describes a location on the page where slot contents can be
+ * rendered (e.g. `submissionAuthor` is a slot type that's rendered next to the
+ * usernames of submission authors).
+ */
+export type PlatformSlotType = keyof PlatformSlotDetails;
 
 // Consumer code (used by toolbox modules)
 
 // A consumer of a particular slot location which gets appropriate context and
 // returns React content to be rendered in the slot
-export type PlatformSlotContent<Location extends keyof PlatformSlotDetails> = ComponentType<{
-    details: PlatformSlotDetails[Location];
-    location: Location;
+export type PlatformSlotContent<SlotType extends keyof PlatformSlotDetails> = ComponentType<{
+    /**
+     * Contextual details about the content the slot is attached to. Different
+     * slot types provide different information in this object.
+     */
+    details: PlatformSlotDetails[SlotType];
+    /** The type of slot the component is currently being populated into. */
+    slotType: SlotType;
 }>;
 
 // Map of slot locations to consumers of the slot
 const slotConsumers: {
     [K in keyof PlatformSlotDetails]?: PlatformSlotContent<K>[];
 } = Object.create(null);
 
-// NOMERGE: document
-export function renderInSlots<K extends keyof PlatformSlotDetails> (locations: K[], render: PlatformSlotContent<K>) {
-    if (!Array.isArray(locations)) {
-        locations = [];
+/**
+ * Provide a consumer for one or more slot types. Whenever any of the `slots`
+ * appears on the page, the given component/renderer will be used to populate
+ * the slot (alongside any other consumers of the same slot type).
+ * @param slots An array of slots where the given component should be rendered
+ * @param render A React function component/render function that will be
+ * rendered in those slots. Props are passed which inform the component which
+ * type of slot it's currently being rendered in, and contextual information
+ * about the slot's surroundings.
+ */
+export function renderInSlots<K extends keyof PlatformSlotDetails> (slots: K[], render: PlatformSlotContent<K>) {
+    if (!Array.isArray(slots)) {
+        slots = [];
     }
-    for (const location of locations) {
-        if (!slotConsumers[location]) {
-            slotConsumers[location] = [];
+    for (const slot of slots) {
+        if (!slotConsumers[slot]) {
+            slotConsumers[slot] = [];
         }
-        slotConsumers[location]?.push(render);
+        slotConsumers[slot]?.push(render);
     }
 }
 
 // Observer code (used by platform-specific observers in this directory)
 
-// NOMERGE: document
+/**
+ * A platform observer is a function responsible creating slot instances and
+ * attaching them to the page in the appropriate locations for a specific
+ * platform. It is called once when Toolbox starts and receives a function which
+ * creates slot instances, which it then inserts into the DOM.
+ */
 export type PlatformObserver = (
     /**
      * Creates a React root for a slot which will be populated with the
      * appropriate contents. Observers are responsible for calling this function
      * and inserting the resulting element into the DOM wherever the slot should
      * be rendered.
      */
-    createRenderer: <Location extends keyof PlatformSlotDetails>(
-        location: Location,
-        details: PlatformSlotDetails[Location],
+    createRenderer: <SlotType extends keyof PlatformSlotDetails>(
+        slotType: SlotType,
+        details: PlatformSlotDetails[SlotType],
     ) => HTMLElement,
 ) => void;
 
 // the actual `createRenderer` function observers get - returns a new react root
 // which will contain all the contents different modules have registered for the
-// given slot location
+// given slot type
 // NOTE: Exported because tbui builders need to manually emit their own slots.
 //       Should we just import this from the platform-specific bits instead of
 //       passing this function in to them?
-export const createRenderer = <K extends keyof PlatformSlotDetails>(location: K, details: PlatformSlotDetails[K]) =>
+export const createRenderer = <K extends keyof PlatformSlotDetails>(slotType: K, details: PlatformSlotDetails[K]) =>
     reactRenderer(
         <div
             className='tb-platform-slot'
             style={{display: 'inline-flex'}} // FIXME: do this in CSS
-            data-location={location}
+            data-slot-type={slotType}
         >
             {/* TODO: Do we want to do anything more sophisticated here? */}
-            {slotConsumers[location]?.map((Component, i) => (
+            {slotConsumers[slotType]?.map((Component, i) => (
                 <Component
                     key={i}
                     details={details}
-                    location={location}
+                    slotType={slotType}
                 />
             ))}
         </div>,

extension/data/modules/historybutton.js

@@ -78,7 +78,7 @@ self.runJsAPI = function () {
         'submissionAuthor',
         'commentAuthor',
         'userHovercard',
-    ], ({details, location}) => {
+    ], ({details, slotType}) => {
         const subreddit = details.subreddit.name;
         const user = !details.user.deleted && details.user.name;
 
@@ -87,7 +87,7 @@ self.runJsAPI = function () {
         }
 
         const $target = $('<span>');
-        self.attachHistoryButton($target, user, subreddit, location === 'userHovercard' ? 'User History' : undefined);
+        self.attachHistoryButton($target, user, subreddit, slotType === 'userHovercard' ? 'User History' : undefined);
         return createElement(JQueryRenderer, {content: $target});
     });
 

extension/data/modules/modbutton.js

@@ -74,7 +74,7 @@ self.runRedesign = async function () {
         'submissionAuthor',
         'commentAuthor',
         'userHovercard',
-    ], ({details, location}) => {
+    ], ({details, slotType}) => {
         const contextFullname = details.contextFullname || details.comment?.fullname || details.submission?.fullname
             || 'unknown';
         const subreddit = details.subreddit.name;
@@ -96,7 +96,7 @@ self.runRedesign = async function () {
                     data-parentID="${contextFullname}"
                     class="global-mod-button tb-bracket-button"
                 >
-                    ${location === 'userHovercard' ? 'Mod Button' : 'M'}
+                    ${slotType === 'userHovercard' ? 'Mod Button' : 'M'}
                 </a>
             `),
         });

extension/data/modules/nukecomments.js

@@ -287,7 +287,7 @@ export default new Module({
     // Add nuke buttons where needed
     // XXX 3: this also needs to be able to appear in hovercards apparently?? what
     // the fuck is going on with all the special casing in this goddamn module
-    renderInSlots(['commentAuthor'], ({details, location}) => {
+    renderInSlots(['commentAuthor'], ({details, slotType}) => {
         const subreddit = details.subreddit.name;
         const commentID = details.comment.fullname.substring(3);
         const submissionID = details.submission?.fullname.substring(3);
@@ -305,7 +305,7 @@ export default new Module({
 
         const NukeButtonHTML =
             `<span class="tb-nuke-button tb-bracket-button" data-comment-id="${commentID}" data-post-id="${submissionID}" data-subreddit="${subreddit}" title="Remove comment chain starting with this comment">${
-                location === 'userHovercard' ? 'Nuke' : 'R'
+                slotType === 'userHovercard' ? 'Nuke' : 'R'
             }</span>`;
 
         // XXX 2: implement showNextToUser setting. for now we always show next

extension/data/modules/usernotes.js

@@ -129,7 +129,7 @@ function startUsernotes ({maxChars, showDate}) {
             'submissionAuthor',
             'commentAuthor',
             'modmailAuthor',
-        ], ({location, details}) => {
+        ], ({slotType, details}) => {
             const subreddit = details.subreddit.name;
             const author = details.user.name;
 
@@ -152,7 +152,7 @@ function startUsernotes ({maxChars, showDate}) {
             );
 
             attachNoteTag($target, subreddit, author, {
-                customText: location === 'userHovercard' ? 'Usernotes' : undefined,
+                customText: slotType === 'userHovercard' ? 'Usernotes' : undefined,
             });
             foundSubreddit(subreddit);
             queueProcessSub(subreddit, $target);