Generating code documentation (jsdoc or similar)

[raphroberts (raph)]

Howdy folks,

I've written a fairly hefty app in Hype and would like to generate documentation of the code to avoid headaches down the line, just wondering if anyone had tips they might share for how to best do this.

I have not used jsdoc before but thought this might be a good use case. If so, would I just copy the code manually into a separate file, use jsdoc notation and compile from there, or perhaps hype has some inbuilt functionality/extensions that would assist?

Please note that we can only address JavaScript questions and issues in the context of Tumult Hype, so please attach a Hype document so others can dig into what you have so far.

[MaxZieb (Loves Hype)]

In general, you can define most functions using Hype Events and have them in an external file as we speak … see my examples found on GitHub. I am only using JSDOC on functions that are exposed to my documentation and regular comments for private functions, though.

If you need them in Hype you can call them by forwarding them from within the Hype Function

Sidenote: Just realized the DoxDox server (live repository documentation) is down.
Contacted the creator, but that is beside the point here.

Another thing but with an export script dependency: The upcoming Hype Bundles extracts all user functions into the generated script … only thing missing would be to have a JSDOC notion from within the function and add it to the extracted function.

[raphroberts (raph)]

Thank you for your reply Max, much appreciated.

What is "The upcoming Hype Bundles" - is this an extension project, or are you referring to the next version of Hype?

When you say 'forward them from within the Hype function', are you referring to the techniques outlined here: Calling Hype Function from External Library - Function Library - Tumult Forums or something different?

[MaxZieb (Loves Hype)]

@raphroberts

What is "The upcoming Hype Bundles" - is this an extension project, or are you referring to the next version of Hype?

I'd wish! No… its just a user project offering some nice extendibility and features.

@raphroberts

When you say 'forward them from within the Hype function', are you referring to the techniques outlined here: Calling Hype Function from External Library - Function Library - Tumult Forums or something different?

This is the common way to write a Hype event.

worldoptimizer/HypeCookBook - Register Hype Eventlistener

What I mean is you can define functions that way and in your regular Hype functions just forward them to the external function

function HypeDocumentLoad(hypeDocument, element, event) {

	/** 
	 * Your function description with regular signature
	 * @param {Object} hypeDocument The object containing the Hype API
	 * @param {HTMLDivElement} element The current element
	 * @param {Object} event The name you want to print
	 */
	 hypeDocument.someName = function(hypeDocument, element, event) {
		// do something
	}
}

if("HYPE_eventListeners" in window === false) { window.HYPE_eventListeners = Array(); }
window.HYPE_eventListeners.push({"type":"HypeDocumentLoad", "callback":HypeDocumentLoad});

In Hype you can just forward your calls to the ones you defined external with added JSDOC.

[MaxZieb (Loves Hype)]

Doxdox is back up the developer said:

Thank you for messaging me about this! I was unaware that the site was down. I have fixed the issue and restarted the heroku instance. doxdox was a passion project for me for a long time, back when I was primarily a web developer. Now that I work in game development, I don't have as much time for projects like this one. I do plan on revisiting it at some point in the future.

Here is an example how I use the service to extract documentation from my GitHub projects using JSDOC). I highly recommend tools like these as they really help in bringing the time down when creating documentation (at least technical oriented stuff).

Hype DataDecorator

You can read about the steps necessary to make it work here:
https://doxdox.org/

[raphroberts (raph)]

Much appreciated Max, this is great information.

Thanks also for the wiki link, there's a lot of great stuff to explore there.