Script documentation format for Javascript

[sankethkatta]

I am writing my script files in Javascript as opposed to Coffeescript and I keep getting an error with my documentation:

[Fri Nov 13 2015 15:15:54 GMT-0800 (PST)] INFO /home/sankethkatta/hubot/scripts/example.js is using deprecated documentation syntax

I am trying to follow the convention explained in the docs: https://github.com/github/hubot/blob/master/docs/scripting.md#documenting-scripts

I've tried replacing the # with // as well as a block style:

/**
 * <all the docs here>
 */

I still get the same error, no matter how I format it. Is there a preferred way of documenting for Javascript?

[technicalpickles]

@sankethkatta I actually opened an issue just the other day for this over at https://github.com/github/hubot/issues/1087

Would you mind posting over there? I think help command parsing might be expecting coffeescript.

[technicalpickles]

Sorry, just saw the title update. It's good to leave this open, but https://github.com/github/hubot/issues/1087 is still of interest :grin:

[sankethkatta]

@technicalpickles do you mean https://github.com/github/hubot/issues/1082? Changed the title as soon as I came across that!

[sankethkatta]

Looking at the parseHelp method in robot.coffee#L505. I found that the // comment format works:

// Description:
//   <description of the scripts functionality>
// ...

However, it must be the first line of the file or parseHelp stops parsing the file. It is important to note that the doc must come before any other code. My issue was that I was using a 'use strict'; declaration at the top of the file.

So your file should really look like this with any other require statements also written after the doc:

// Description:
//   <description of the scripts functionality>
// ...

'use strict';

var util = require('util');

module.exports = function(robot) { ... }

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[technicalpickles]

This will be more relevant as hubot's core is in javascript, and that will become the recommended way to write scripts. cc https://github.com/hubotio/evolution/pull/4

[svodnik]

I'm still encountering this error message. I have just a script.js file, and no other files in /scripts. My file starts off with several lines commented with // before getting to any code. I have other line comments later in the file -- could this be causing the issue? I took a cursory glance at the robot.coffee code referenced above, but didn't totally get my head around it. If nothing else, this is a heads up that simply making this the recommended way to write scripts won't necessarily resolve this issue.

[huiminzeng]

Hello, i stuck with this problem as well. Any updates? Thx

[Romanski1]

https://github.com/Romanski1

[joeyguerra]

A new version was just released. Can you try it again and see if the error still persists?