Skip to content

Update dependencies & API docs #607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Mar 8, 2023
Merged
Prev Previous commit
Next Next commit
docs: Use /** comments */ where appropriate
Also drop a few unnecessary eslint directive comments
  • Loading branch information
eemeli committed Feb 14, 2023
commit 1ceb0bf2a62fb9e8926ba8fc97550d5d7f56ed89
36 changes: 20 additions & 16 deletions fluent-bundle/src/resolver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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>,
Expand All @@ -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>
Expand All @@ -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":
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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") {
Expand Down
8 changes: 5 additions & 3 deletions fluent-bundle/src/scope.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
2 changes: 0 additions & 2 deletions fluent-bundle/src/types.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
import { Scope } from "./scope.js";

/* global Intl */

export type FluentValue = FluentType<unknown> | string;

export type FluentFunction = (
Expand Down
4 changes: 2 additions & 2 deletions fluent-gecko/rollup.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
Expand All @@ -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,
Expand Down
4 changes: 0 additions & 4 deletions fluent-gecko/src/fluent-syntax.js
Original file line number Diff line number Diff line change
@@ -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";
Expand Down
2 changes: 1 addition & 1 deletion fluent-react/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/*
/**
* @module fluent-react
* @overview
*
Expand Down
2 changes: 1 addition & 1 deletion fluent-react/src/localization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import voidElementTags from "../vendor/voidElementTags.js";
// &amp;, &#0038;, &#x0026;.
const reMarkup = /<|&#?\w+;/;

/*
/**
* `ReactLocalization` handles translation formatting and fallback.
*
* The current negotiated fallback chain of languages is stored in the
Expand Down
2 changes: 1 addition & 1 deletion fluent-react/src/localized.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down
12 changes: 6 additions & 6 deletions fluent-react/src/markup.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion fluent-react/src/provider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion fluent-react/src/use_localization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 };
Expand Down
2 changes: 1 addition & 1 deletion fluent-sequence/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/*
/**
* @module fluent-sequence
* @overview Manage ordered sequences of FluentBundles.
*/
Expand Down
2 changes: 1 addition & 1 deletion fluent-sequence/src/map_async.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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).
*
Expand Down
2 changes: 1 addition & 1 deletion fluent-sequence/src/map_sync.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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).
*
Expand Down
4 changes: 2 additions & 2 deletions fluent-syntax/src/ast.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/*
/**
* Base class for all Fluent AST nodes.
*
* All productions described in the ASDL subclass BaseNode, including Span and
Expand Down Expand Up @@ -77,7 +77,7 @@ function scalarsEqual(
return thisVal === otherVal;
}

/*
/**
* Base class for AST nodes which can have Spans.
*/
export abstract class SyntaxNode extends BaseNode {
Expand Down
30 changes: 18 additions & 12 deletions fluent-syntax/src/parser.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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()) {
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion fluent-syntax/src/serializer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
7 changes: 3 additions & 4 deletions fluent-syntax/src/stream.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion rollup.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ export default async function () {
format: "umd",
amd: { id: name },
name: globalName[name],
banner: `/* ${name}@${version} */`,
banner: `/** ${name}@${version} */`,
},
};
}