Documentation could be improved

[Antix-Development]

I finally got some spare time and started to read through the LittleJS documentation in order to gain some deeper understanding of what does what and how it does it.

What I discovered...

• Not all code has the same coding style. Some files (engineDebug, engineExports) use fatarrow function declarations exclusively, whereas most other files use traditional js function declarations. Meanwhile, other files have a mixture of fatarrow and traditional function declarations (engine, engineDraw, engineInput). Would it be better to choose one declaration style and stick with that?

• The engineAudio.js file has at least one function that contains no @params in its jsdoc. It also has no namespace assigned to it, and functions in the file that are not part of classes don't seem to be present in the docs as a result.

• Most files contain @return tags but there are also some @returns tags. Even though they are basically the same, consistency would be nice.

• Many @default tags don't have any actual values.

• Some js files have a bunch of HTML
  scattered throughout them and others do not. Again it might be good if they were all formatted in a consistent manner.

• The zzfxG function in engineAudio has no @param tags.

• engine.js has no @namespace tag in it's header comment, but other js files do. Would it be better if they had consistent formatting?

• Some js files contain @property tags which seem to be not required.

• engineUtilities.js contains multiple namespaces.

What I did...

Well I made a web application that loads JavaScript files and generates HTML documentation from their embedded JsDocs.

I used that to generate a new document for LittleJS and used that as a live example of what it does.

Anyhoo, that's kind of an aside. Let me know what you think.. I'm happy to help however I can.

[KilledByAPixel]

Hey Cliff, thanks so much, this is great feedback!

I will review all this stuff and get back to you shortly.

[KilledByAPixel]

Ok, I just pushed an update to address most of this!

Not all code has the same coding style. Some files (engineDebug, engineExports) use fatarrow function declarations exclusively, whereas most other files use traditional js function declarations. Meanwhile, other files have a mixture of fatarrow and traditional function declarations (engine, engineDraw, engineInput). Would it be better to choose one declaration style and stick with that?

I replaced all top level arrow functions with the function keyword.

The engineAudio.js file has at least one function that contains no @params in its jsdoc. It also has no namespace assigned to it, and functions in the file that are not part of classes don't seem to be present in the docs as a result.

Fixed!

Most files contain @return tags but there are also some @returns tags. Even though they are basically the same, consistency would be nice.

Fixed!

Many @default tags don't have any actual values.

This is intentional, JSDoc will replace with the correct value. "You can supply this tag with a value yourself or you can allow JSDoc to automatically document the value from the source code -- only possible when the documented symbol is being assigned a single, simple value that is either: a string, a number, a boolean or null."

Some js files have a bunch of HTML scattered throughout them and others do not. Again it might be good if they were all formatted in a consistent manner.

Maybe this was from the docs there was some
and other html, I got rid of it as it is no longer necessary. I left anchor links in a few places that seem to work well.

The zzfxG function in engineAudio has no @param tags.

Fixed!

engine.js has no @namespace tag in it's header comment, but other js files do. Would it be better if they had consistent formatting?

Fixed!

Some js files contain @Property tags which seem to be not required.

Where are you seeing this where it is not required? The property tag is used by properties of classes.

engineUtilities.js contains multiple namespaces.

This is allowed as far as I know. There is a separate namespace for Random and it shows up correctly with JSDocs.

Well I made a web application that loads JavaScript files and generates HTML documentation from their embedded JsDocs.

That is really awesome! If you could get this working as well as JSDocs then I would definitely consider using it and a lot of other people probably would too. Keep up the good work!

[Antix-Development]

Thanks Frank, I'm amazed you got this all done so quickly!

You are correct re the @property tags, they actually do serve a purpose :)

I really just thought (at the time) that it was odd to have multiple namespaces inside a file but yes, it's valid.

Thanks for the feedback on my little app. I don't know if it would be widely used since it's not able to run without some user interaction, so it couldn't be used as part of an automated build process. For now it's good enough for my own use but I do want to at least add some color editing functionality to it.