Documenting Handlebars helpers #68

wagenet · 2012-08-30T17:50:32Z

I'm attempting to write documentation for Handlebars helpers. Unfortunately, YUIDoc wants to evaluate all of them. Is there a workaround?

davglass · 2012-08-30T18:42:34Z

Escape them them a \{ and it should work.

wagenet · 2012-08-30T19:05:24Z

I set up the code as:

\{{myHelper}}

However, that still gives me a warning when I build:

Error: Could not find property 'myHelper'

If I do

{\{myHelper}}

it works, but it also displays in the end the same way so I'd have to change the builder to swap that out.

davglass · 2012-08-30T19:43:58Z

You have to escape both sides of the handlebars

In my local tests, both of these work (auto escape in code block):

This is my `{{helper}}foo{{/helper}}`

And with the slashes

This is my \{{helper\}}foo\{{/helper\}}`

wagenet · 2012-08-30T22:03:30Z

This works, but not for code blocks, either indented or backtick. One error looks like this:

Error: Parse error on line 11:
...  &lt;div \{{action anActionName\}}&gt;
-----------------------^
Expecting 'CLOSE', 'STRING', 'INTEGER', 'BOOLEAN', 'ID', 'SEP', got 'INVALID'
    at Object.i [as parseError] (/Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:12:6435)
    at Object.k [as parse] (/Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:13:1135)
    at Object.parse (/Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:14:1613)
    at h (/Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:16:5053)
    at /Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:16:5211
    at Object.markdown (/Users/peterwagenet/Development/JavaScript/yuidoc/lib/builder.js:145:51)
    at [object Object].<anonymous> (/Users/peterwagenet/Development/JavaScript/yuidoc/lib/builder.js:651:34)
    at Function.each (/Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/yui-nodejs/yui-nodejs.js:3173:16)
    at f (/Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/oop/oop-min.js:7:296)
    at [object Object].each (/Users/peterwagenet/Development/JavaScript/yuidoc/node_modules/yui/oop/oop-min.js:7:1206)

wagenet · 2012-08-30T22:06:08Z

Further examination leads me to believe that it's not the code block that's actually the problem. Instead it appears that only the first commented out helper is ignored. It seems as if Handlebars is still attempting to parse the first helper in some fashion.

dmitris · 2012-09-13T14:20:25Z

See also http://yuilibrary.com/projects/yui3/ticket/2532750 - the YUI3 API docs are wrong due to this issue.

When I copy https://github.com/yui/yui3/blob/master/src/handlebars/js/yui-handlebars-base-after.js and run yuidoc . , it fails with the following errors:

$ yuidoc .
info: (yuidoc): Starting YUIDoc@0.3.22 using YUI@3.6.0 with NodeJS@0.6.21-pre
info: (yuidoc): Scanning for yuidoc.json file.
info: (yuidoc): Loading project data from: /Users/dimisec/dev/test/yuidoc/yuidoc.json
info: (yuidoc): Starting YUIDoc with the following options:
info: (yuidoc):
{ linkNatives: 'true',
attributesEmit: 'true',
selleck: 'true',
ignorePaths: [ 'simpleyui' ],
paths: [ '.' ],
outdir: '../api-js',
port: 3000,
nocode: false,
project:
{ name: 'YUI 3',
description: 'YUI 3 JavaScript Framework',
version: '3.6.0',
url: 'http://yuilibrary.com/' } }
info: (yuidoc): YUIDoc Starting from: .
warn: (yuidoc): Found out dir, deleting: ../api-js
info: (yuidoc): Making out dir: ../api-js
info: (yuidoc): Parsed 1 files in 0.012 seconds
info: (builder): Building..
info: (builder): Compiling Templates
info: (builder): Making default directories: classes,modules,files
info: (builder): Copying Assets
info: (builder): Rendering and writing 2 modules pages.
info: (builder): Loading theme from /Users/dimisec/.nvm/v0.6.21/lib/node_modules/yuidocjs/themes/default/theme.json
info: (builder): Preparing index.html
info: (builder): Writing API Meta Data
info: (builder): Finished writing module files
info: (builder): Rendering and writing 1 class pages.
error: --------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error:
Error: Parse error on line 6:
...links}}<li>{{{#linkify}}}</li&g
-----------------------^
Expecting 'ID', got 'INVALID'
at Object.i as parseError
at Object.k as parse
at Object.parse (/Users/dimisec/.nvm/v0.6.21/lib/node_modules/yuidocjs/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:14:1613)
at h (/Users/dimisec/.nvm/v0.6.21/lib/node_modules/yuidocjs/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:16:5053)
at /Users/dimisec/.nvm/v0.6.21/lib/node_modules/yuidocjs/node_modules/yui/handlebars-compiler/handlebars-compiler-min.js:16:5211
at Object.markdown (/Users/dimisec/.nvm/v0.6.21/lib/node_modules/yuidocjs/lib/builder.js:145:51)
at /Users/dimisec/.nvm/v0.6.21/lib/node_modules/yuidocjs/lib/builder.js:1158:67
at Array.forEach (native)
at /Users/dimisec/.nvm/v0.6.21/lib/node_modules/yuidocjs/lib/builder.js:1157:47
at Array.forEach (native)
error: --------------------------------------------------------------------------
error: Node.js version: v0.6.21-pre
error: YUI version: 3.6.0
error: YUIDoc version: 0.3.22
error: Please file all tickets here: http://github.com/yui/yuidoc/issues
error: --------------------------------------------------------------------------

dmitris · 2012-09-13T14:22:49Z

I believe the problem is here:
https://github.com/yui/yuidoc/blob/master/lib/builder.js#L141

    markdown: function(md, def, tags) {
        html = MD(md, def, tags);
        if (html.indexOf('{{#') > -1) { //Only reprocess with Handlebars if we see a helper
            //console.log('MD: ', html);
            html = (Y.Handlebars.compile(html))({});
            //console.log('HB: ', html);
        }
        return html;
    },

If I remove # from {{# in the comment section, the error goes away

wagenet · 2012-09-13T14:38:47Z

@dmitris The code you linked basically is just to only reparse handlebars if there's a block helper. Apparently, all YUIDoc helpers are block helpers. The problem still stands that there's no way to escape handlebars helpers to avoid processing.

dmitris · 2012-09-13T15:02:03Z

I think the proper way to escape handlebars helpers should be documented at the end of http://yui.github.com/yuidoc/syntax/index.html, maybe in the separate subsection "Escaping Handlebars Helpers Syntax"

wagenet · 2012-09-13T15:09:41Z

@dmitris Agreed. My problem is that I can't even find a way that works. Much less one that is documented.

davglass · 2012-09-14T03:05:03Z

Yeah, yuidoc tries to "reparse" the code if it finds a helper so they can be used in your docs.

It may be stripping the escape the first time & trying to handle it the second time. I'll look into this tomorrow.

dmitris · 2012-09-14T10:42:12Z

http://yui.github.com/yuidoc/syntax/index.html says in "Extra formatting":
YUIDoc supports 3 main forms of formatting your documentation. HTML, Markdown & Selleck.
Inside any documentation block you may use Markdown or Selleck based markup.

but is it "may use" or "must use"? Markdown lists a number of characters for which there is an escape sequence:
http://daringfireball.net/projects/markdown/syntax#backslash

Which of them should be escaped in the yuidoc comment blocks and in which cases?

@wagenet I understand that there is some prerequisite work, possibly yuidoc fix that needs to be done - just wanted to put thoughts about documentation for later

…d tests will fail. Ref #68

davglass · 2012-09-14T14:48:23Z

This is in 0.3.23

ghost assigned davglass Sep 14, 2012

davglass closed this as completed in b7f48fa Sep 14, 2012

davglass added a commit that referenced this issue Sep 14, 2012

Added some extra Handlebars code, if this throws there is an issue an…

8cb709e

…d tests will fail. Ref #68

kidonchu mentioned this issue Mar 16, 2017

Unable to include handlebar example while using block helper within same doc block #433

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documenting Handlebars helpers #68

Documenting Handlebars helpers #68

wagenet commented Aug 30, 2012

davglass commented Aug 30, 2012

wagenet commented Aug 30, 2012

davglass commented Aug 30, 2012

wagenet commented Aug 30, 2012

wagenet commented Aug 30, 2012

dmitris commented Sep 13, 2012

dmitris commented Sep 13, 2012

wagenet commented Sep 13, 2012

dmitris commented Sep 13, 2012

wagenet commented Sep 13, 2012

davglass commented Sep 14, 2012

dmitris commented Sep 14, 2012

davglass commented Sep 14, 2012

Documenting Handlebars helpers #68

Documenting Handlebars helpers #68

Comments

wagenet commented Aug 30, 2012

davglass commented Aug 30, 2012

wagenet commented Aug 30, 2012

davglass commented Aug 30, 2012

wagenet commented Aug 30, 2012

wagenet commented Aug 30, 2012

dmitris commented Sep 13, 2012

dmitris commented Sep 13, 2012

wagenet commented Sep 13, 2012

dmitris commented Sep 13, 2012

wagenet commented Sep 13, 2012

davglass commented Sep 14, 2012

dmitris commented Sep 14, 2012

davglass commented Sep 14, 2012