Boilerplate removal is unconditional, and among the lines it removes are the calls to SourceCodeViewer.highlight, SourceCodeViewer.highlightOnHover and SourceCodeViewer.highlightOnClick. As a result the fragment highlighting feature cannot be demoed: the very calls that a demo needs to show are the ones that are hidden.
// hide-source already works as a suffix (a line ending with that comment is removed), but // show-source is only recognized as a prefix, where it renders a comment as if it were code. There is no way to keep a line that boilerplate removal would otherwise hide.
Proposal
A line that ends with a // show-source comment is always rendered, and the comment itself is removed, so the line is rendered as it is written:
SourceCodeViewer.highlightOnHover(div, "first"); // show-source
is rendered as:
SourceCodeViewer.highlightOnHover(div, "first");
This makes the suffix form of show-source the counterpart of the suffix form of hide-source, and the override is opt-in per line, so boilerplate removal is unchanged for every source that does not use it.
Notes
The prefix form (synthetic source) keeps its current meaning. Overriding the removal with the prefix form is possible today, but only by duplicating the line: a commented copy that is rendered plus the real call that is hidden, as CleanupOverride does for @Route. That is not acceptable for lines that must both execute and be shown.
Boilerplate removal is unconditional, and among the lines it removes are the calls to
SourceCodeViewer.highlight,SourceCodeViewer.highlightOnHoverandSourceCodeViewer.highlightOnClick. As a result the fragment highlighting feature cannot be demoed: the very calls that a demo needs to show are the ones that are hidden.// hide-sourcealready works as a suffix (a line ending with that comment is removed), but// show-sourceis only recognized as a prefix, where it renders a comment as if it were code. There is no way to keep a line that boilerplate removal would otherwise hide.Proposal
A line that ends with a
// show-sourcecomment is always rendered, and the comment itself is removed, so the line is rendered as it is written:is rendered as:
This makes the suffix form of
show-sourcethe counterpart of the suffix form ofhide-source, and the override is opt-in per line, so boilerplate removal is unchanged for every source that does not use it.Notes
The prefix form (synthetic source) keeps its current meaning. Overriding the removal with the prefix form is possible today, but only by duplicating the line: a commented copy that is rendered plus the real call that is hidden, as
CleanupOverridedoes for@Route. That is not acceptable for lines that must both execute and be shown.