docs: Use /** comments */ where appropriate

Also drop a few unnecessary eslint directive comments

fluent-bundle/src/resolver.ts

@@ -46,16 +46,18 @@ import {
 } from "./ast.js";
 import { FluentVariable } from "./bundle.js";
 
-// The maximum number of placeables which can be expanded in a single call to
-// `formatPattern`. The limit protects against the Billion Laughs and Quadratic
-// Blowup attacks. See https://msdn.microsoft.com/en-us/magazine/ee335713.aspx.
+/**
+ * The maximum number of placeables which can be expanded in a single call to
+ * `formatPattern`. The limit protects against the Billion Laughs and Quadratic
+ * Blowup attacks. See https://msdn.microsoft.com/en-us/magazine/ee335713.aspx.
+ */
 const MAX_PLACEABLES = 100;
 
-// Unicode bidi isolation characters.
+/** Unicode bidi isolation characters. */
 const FSI = "\u2068";
 const PDI = "\u2069";
 
-// Helper: match a variant key to the given selector.
+/** Helper: match a variant key to the given selector. */
 function match(scope: Scope, selector: FluentValue, key: FluentValue): boolean {
   if (key === selector) {
     // Both are strings.
@@ -86,7 +88,7 @@ function match(scope: Scope, selector: FluentValue, key: FluentValue): boolean {
   return false;
 }
 
-// Helper: resolve the default variant from a list of variants.
+/** Helper: resolve the default variant from a list of variants. */
 function getDefault(
   scope: Scope,
   variants: Array<Variant>,
@@ -105,7 +107,7 @@ interface Arguments {
   named: Record<string, FluentValue>;
 }
 
-// Helper: resolve arguments to a call expression.
+/** Helper: resolve arguments to a call expression. */
 function getArguments(
   scope: Scope,
   args: Array<Expression | NamedArgument>
@@ -124,7 +126,7 @@ function getArguments(
   return { positional, named };
 }
 
-// Resolve an expression to a Fluent type.
+/** Resolve an expression to a Fluent type. */
 function resolveExpression(scope: Scope, expr: Expression): FluentValue {
   switch (expr.type) {
     case "str":
@@ -148,7 +150,7 @@ function resolveExpression(scope: Scope, expr: Expression): FluentValue {
   }
 }
 
-// Resolve a reference to a variable.
+/** Resolve a reference to a variable. */
 function resolveVariableReference(
   scope: Scope,
   { name }: VariableReference
@@ -197,7 +199,7 @@ function resolveVariableReference(
   }
 }
 
-// Resolve a reference to another message.
+/** Resolve a reference to another message. */
 function resolveMessageReference(
   scope: Scope,
   { name, attr }: MessageReference
@@ -225,7 +227,7 @@ function resolveMessageReference(
   return new FluentNone(name);
 }
 
-// Resolve a call to a Term with key-value arguments.
+/** Resolve a call to a Term with key-value arguments. */
 function resolveTermReference(
   scope: Scope,
   { name, attr, args }: TermReference
@@ -256,7 +258,7 @@ function resolveTermReference(
   return resolved;
 }
 
-// Resolve a call to a Function with positional and key-value arguments.
+/** Resolve a call to a Function with positional and key-value arguments. */
 function resolveFunctionReference(
   scope: Scope,
   { name, args }: FunctionReference
@@ -283,7 +285,7 @@ function resolveFunctionReference(
   }
 }
 
-// Resolve a select expression to the member object.
+/** Resolve a select expression to the member object. */
 function resolveSelectExpression(
   scope: Scope,
   { selector, variants, star }: SelectExpression
@@ -304,7 +306,7 @@ function resolveSelectExpression(
   return getDefault(scope, variants, star);
 }
 
-// Resolve a pattern (a complex string with placeables).
+/** Resolve a pattern (a complex string with placeables). */
 export function resolveComplexPattern(
   scope: Scope,
   ptn: ComplexPattern
@@ -356,8 +358,10 @@ export function resolveComplexPattern(
   return result.join("");
 }
 
-// Resolve a simple or a complex Pattern to a FluentString (which is really the
-// string primitive).
+/**
+ * Resolve a simple or a complex Pattern to a FluentString
+ * (which is really the string primitive).
+ */
 function resolvePattern(scope: Scope, value: Pattern): FluentValue {
   // Resolve a simple pattern.
   if (typeof value === "string") {

fluent-bundle/src/scope.ts

@@ -8,13 +8,15 @@ export class Scope {
   public errors: Array<Error> | null;
   /** A dict of developer-provided variables. */
   public args: Record<string, FluentVariable> | null;
-  /** The Set of patterns already encountered during this resolution.
+  /**
+   * The Set of patterns already encountered during this resolution.
    * Used to detect and prevent cyclic resolutions. */
   public dirty: WeakSet<ComplexPattern> = new WeakSet();
   /** A dict of parameters passed to a TermReference. */
   public params: Record<string, FluentVariable> | null = null;
-  /** The running count of placeables resolved so far. Used to detect the
-   * Billion Laughs and Quadratic Blowup attacks. */
+  /**
+   * The running count of placeables resolved so far.
+   * Used to detect the Billion Laughs and Quadratic Blowup attacks. */
   public placeables: number = 0;
 
   constructor(

fluent-bundle/src/types.ts

@@ -1,7 +1,5 @@
 import { Scope } from "./scope.js";
 
-/* global Intl */
-
 export type FluentValue = FluentType<unknown> | string;
 
 export type FluentFunction = (

fluent-gecko/rollup.config.mjs

@@ -33,7 +33,7 @@ export default [
       format: "cjs",
       generatedCode: { constBindings: true },
       banner: license,
-      intro: `/* fluent-react@${reactPkg.version} */`,
+      intro: `/** fluent-react@${reactPkg.version} */`,
     },
     context: "this",
     external: ["react"],
@@ -47,7 +47,7 @@ export default [
       freeze: false,
       generatedCode: { constBindings: true },
       banner: `${vim}\n\n${license}`,
-      intro: `/* fluent-syntax@${syntaxPkg.version} */`,
+      intro: `/** fluent-syntax@${syntaxPkg.version} */`,
     },
     context: "this",
     treeshake: false,

fluent-gecko/src/fluent-syntax.js

@@ -1,7 +1,3 @@
-/* eslint object-shorthand: "off",
-          comma-dangle: "off",
-          no-labels: "off" */
-
 import { FluentParser } from "../../fluent-syntax/esm/parser.js";
 import { FluentSerializer } from "../../fluent-syntax/esm/serializer.js";
 import { Visitor, Transformer } from "../../fluent-syntax/esm/visitor.js";

fluent-react/src/index.ts

@@ -1,4 +1,4 @@
-/*
+/**
  * @module fluent-react
  * @overview
  *

fluent-react/src/localization.ts

@@ -15,7 +15,7 @@ import voidElementTags from "../vendor/voidElementTags.js";
 // &, &, &.
 const reMarkup = /<|&#?\w+;/;
 
-/*
+/**
  * `ReactLocalization` handles translation formatting and fallback.
  *
  * The current negotiated fallback chain of languages is stored in the

fluent-react/src/localized.ts

@@ -14,7 +14,7 @@ export interface LocalizedProps {
   vars?: Record<string, FluentVariable>;
   elems?: Record<string, ReactElement>;
 }
-/*
+/**
  * The `Localized` class renders its child with translated props and children.
  *
  *     <Localized id="hello-world">

fluent-react/src/markup.ts

@@ -1,12 +1,12 @@
-/* eslint-env browser */
-
 export type MarkupParser = (str: string) => Array<Node>;
 let cachedParseMarkup: MarkupParser;
 
-// We use a function creator to make the reference to `document` lazy. At the
-// same time, it's eager enough to throw in <LocalizationProvider> as soon as
-// it's first mounted which reduces the risk of this error making it to the
-// runtime without developers noticing it in development.
+/**
+ * We use a function creator to make the reference to `document` lazy. At the
+ * same time, it's eager enough to throw in `<LocalizationProvider>` as soon as
+ * it's first mounted which reduces the risk of this error making it to the
+ * runtime without developers noticing it in development.
+ */
 export function createParseMarkup(): MarkupParser {
   if (typeof document === "undefined") {
     // We can't use <template> to sanitize translations.

fluent-react/src/provider.ts

@@ -7,7 +7,7 @@ interface LocalizationProviderProps {
   l10n: ReactLocalization;
 }
 
-/*
+/**
  * The Provider component for the `ReactLocalization` class.
  *
  * Exposes a `ReactLocalization` instance to all descendants via React's

fluent-react/src/use_localization.ts

@@ -2,7 +2,7 @@ import { useContext } from "react";
 import { FluentContext } from "./context.js";
 import { ReactLocalization } from "./localization.js";
 
-/*
+/**
  * The `useLocalization` hook returns the FluentContext
  */
 type useLocalization = () => { l10n: ReactLocalization };

fluent-sequence/src/index.ts

@@ -1,4 +1,4 @@
-/*
+/**
  * @module fluent-sequence
  * @overview Manage ordered sequences of FluentBundles.
  */

fluent-sequence/src/map_async.ts

@@ -10,7 +10,7 @@ export function mapBundleAsync(
   ids: Array<string>
 ): Promise<Array<FluentBundle | null>>;
 
-/*
+/**
  * Asynchronously map an identifier or an array of identifiers to the best
  * `FluentBundle` instance(s).
  *

fluent-sequence/src/map_sync.ts

@@ -10,7 +10,7 @@ export function mapBundleSync(
   ids: Array<string>
 ): Array<FluentBundle | null>;
 
-/*
+/**
  * Synchronously map an identifier or an array of identifiers to the best
  * `FluentBundle` instance(s).
  *

fluent-syntax/src/ast.ts

@@ -1,4 +1,4 @@
-/*
+/**
  * Base class for all Fluent AST nodes.
  *
  * All productions described in the ASDL subclass BaseNode, including Span and
@@ -77,7 +77,7 @@ function scalarsEqual(
   return thisVal === otherVal;
 }
 
-/*
+/**
  * Base class for AST nodes which can have Spans.
  */
 export abstract class SyntaxNode extends BaseNode {

fluent-syntax/src/parser.ts

@@ -122,7 +122,7 @@ export class FluentParser {
     return res;
   }
 
-  /*
+  /**
    * Parse the first Message or Term in `source`.
    *
    * Skip all encountered comments and start parsing at the first Message or
@@ -421,12 +421,14 @@ export class FluentParser {
     return new AST.NumberLiteral(value);
   }
 
-  // maybeGetPattern distinguishes between patterns which start on the same line
-  // as the identifier (a.k.a. inline signleline patterns and inline multiline
-  // patterns) and patterns which start on a new line (a.k.a. block multiline
-  // patterns). The distinction is important for the dedentation logic: the
-  // indent of the first line of a block pattern must be taken into account when
-  // calculating the maximum common indent.
+  /**
+   * maybeGetPattern distinguishes between patterns which start on the same line
+   * as the identifier (a.k.a. inline signleline patterns and inline multiline
+   * patterns) and patterns which start on a new line (a.k.a. block multiline
+   * patterns). The distinction is important for the dedentation logic: the
+   * indent of the first line of a block pattern must be taken into account when
+   * calculating the maximum common indent.
+   */
   maybeGetPattern(ps: FluentParserStream): AST.Pattern | null {
     ps.peekBlankInline();
     if (ps.isValueStart()) {
@@ -490,15 +492,19 @@ export class FluentParser {
     return new AST.Pattern(dedented);
   }
 
-  // Create a token representing an indent. It's not part of the AST and it will
-  // be trimmed and merged into adjacent TextElements, or turned into a new
-  // TextElement, if it's surrounded by two Placeables.
+  /**
+   * Create a token representing an indent. It's not part of the AST and it will
+   * be trimmed and merged into adjacent TextElements, or turned into a new
+   * TextElement, if it's surrounded by two Placeables.
+   */
   getIndent(ps: FluentParserStream, value: string, start: number): Indent {
     return new Indent(value, start, ps.index);
   }
 
-  // Dedent a list of elements by removing the maximum common indent from the
-  // beginning of text lines. The common indent is calculated in getPattern.
+  /**
+   * Dedent a list of elements by removing the maximum common indent from the
+   * beginning of text lines. The common indent is calculated in getPattern.
+   */
   dedent(
     elements: Array<AST.PatternElement | Indent>,
     commonIndent: number

fluent-syntax/src/serializer.ts

@@ -40,7 +40,7 @@ function shouldStartOnNewLine(pattern: AST.Pattern): boolean {
   return false;
 }
 
-// Bit masks representing the state of the serializer.
+/** Bit masks representing the state of the serializer. */
 const HAS_ENTRIES = 1;
 
 export interface FluentSerializerOptions {

fluent-syntax/src/stream.ts

@@ -225,10 +225,9 @@ export class FluentParserStream extends ParserStream {
     return false;
   }
 
-  // -1 - any
-  //  0 - comment
-  //  1 - group comment
-  //  2 - resource comment
+  /**
+   * @param level - -1: any, 0: comment, 1: group comment, 2: resource comment
+   */
   isNextLineComment(level: number = -1): boolean {
     if (this.currentChar() !== EOL) {
       return false;

rollup.config.mjs

@@ -22,7 +22,7 @@ export default async function () {
       format: "umd",
       amd: { id: name },
       name: globalName[name],
-      banner: `/* ${name}@${version} */`,
+      banner: `/** ${name}@${version} */`,
     },
   };
 }