Skip to content

feat(core/webidl): add data-dfn-for to IDL sections #2893

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.

Sign up for GitHub

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

Draft
sidvishnoi wants to merge 10 commits into
base: main
Choose a base branch
from
Draft

feat(core/webidl): add data-dfn-for to IDL sections #2893

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f6e324c
feat(core/webidl): add data-dfn-for to IDL sections
sidvishnoi May 21, 2020
dd1ad56
maybe not set dfnFor when ambiguous
sidvishnoi May 21, 2020
1cf76e2
export topLevelEntities from dfn-finder.js
sidvishnoi May 21, 2020
e28e2f3
improve error message
sidvishnoi May 21, 2020
79833a6
Error not needed
sidvishnoi May 21, 2020
9184efb
support only single dfnFor
sidvishnoi May 21, 2020
fe08287
add TODO
sidvishnoi May 21, 2020
f0ff768
don't use all those topLevelEntities
sidvishnoi May 21, 2020
95e333b
HOTFIX: test fail as they don't have <section>
sidvishnoi May 21, 2020
08dc4e0
Merge branch 'develop' into idl-automatic-dfn-for
marcoscaceres Apr 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/core/dfn-finder.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
import { definitionMap, registerDefinition } from "./dfn-map.js";
import { showInlineError, wrapInner } from "./utils.js";

const topLevelEntities = new Set([
export const topLevelEntities = new Set([
"callback interface",
"callback",
"dictionary",
Expand Down
33 changes: 32 additions & 1 deletion src/core/webidl.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import {
showInlineWarning,
xmlEscape,
} from "./utils.js";
import { decorateDfn, findDfn } from "./dfn-finder.js";
import { decorateDfn, findDfn, topLevelEntities } from "./dfn-finder.js";
import { html, webidl2 } from "./import-maps.js";
import { addCopyIDLButton } from "./webidl-clipboard.js";
import { fetchAsset } from "./text-loader.js";
Expand Down Expand Up @@ -328,6 +328,7 @@ function renderWebIDL(idlElement, index) {
// Skip this <pre> and move on to the next one.
return [];
}
addDataDfnFor(idlElement, parse);
// we add "idl" as the canonical match, so both "webidl" and "idl" work
idlElement.classList.add("def", "idl");
const highlights = webidl2.write(parse, { templates });
Expand Down Expand Up @@ -358,6 +359,36 @@ function renderWebIDL(idlElement, index) {
addIDLHeader(idlElement);
return parse;
}

/**
* Add data-dfn-for to the closest section if not present already.
* @param {HTMLPreElement} idlElement
* @param {ReturnType<typeof webidl2.parse>} parse
*/
function addDataDfnFor(idlElement, parse) {
const closestSection = idlElement.closest("section");
if (closestSection.hasAttribute("data-dfn-for")) return;

const dfnFors = [];
for (const { tokens } of parse) {
if (topLevelEntities.has(tokens.base.type)) {
const dfnFor = tokens.name.value;
dfnFors.push(dfnFor);
}
}
if (dfnFors.length === 1) {
closestSection.dataset.dfnFor = dfnFors[0];
} else if (!dfnFors.length) {
return;
} else {
// closestSection.dataset.dfnFor = "";
const options = dfnFors.map(dfnFor => `"${dfnFor}"`).join(", ");
Copy link
Copy Markdown
Member Author

@sidvishnoi sidvishnoi May 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should not suggest these options? User might want to add something else?

Copy link
Copy Markdown
Contributor

@marcoscaceres marcoscaceres May 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, don't suggest these yet... remember that this currently works today:

<section data-dfn-for="Whatever">
   
    <section>
    <pre class="idl">
        interface Whatever{};
        interface SomethingElse{};
    <pre>
    </section>
</section>

Copy link
Copy Markdown
Contributor

@marcoscaceres marcoscaceres May 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, the above is probably bad practice and doesn't matter...

const title = "Ambiguous data-dfn-for attribute";
const message = `${title}. Sections describing top-level IDL entities (${topLevelEntities}) require a \`data-dfn-attribute\`. Please add a \`data-dfn-for\` attribute with one of following values: ${options}`;
showInlineError(closestSection, message, title);
}
}

/**
* Adds a "WebIDL" decorative header/permalink to a block of WebIDL.
* @param {HTMLPreElement} pre
Expand Down