Page MenuHomePhabricator

Use JSDuck syntax for inline examples in code documentation
Closed, DeclinedPublic

Description

That is https://github.com/senchalabs/jsduck/wiki/Inline-examples

For instance:

resources/js/ext.translate.editor.js
9: * Example usage:

resources/js/ext.translate.proofread.js
107: * Example usage:

resources/js/ext.translate.pagemode.js
10: * Example usage:

Details

Reference
bz47113

Event Timeline

bzimport raised the priority of this task from to Low.Nov 22 2014, 1:28 AM
bzimport set Reference to bz47113.
bzimport added a subscriber: Unknown Object (MLST).

JSDuck's @example syntax is for a live demo of running code. For OOjs UI and VisualEditor this can be useful in places for classes and methods that are largely about their visual and interactive rendering (not about the shape return value itself). However I'm not sure that's useful in the case of the Translate extension.

To render code examples with syntax highlighting, just use three backticks (or indentation) to create a code section in JSDuck's markdown rendering. Closing this task as it doesn't seem actionable right now.

Right now Translate documentation isn't rendered/published anywhere, so in its current form the code examples are readable as-is. If they are published, one of the three examples will need to be indented for it to be preformatted correctly.