LÖVE

Content Redacted.

Can you give us a rundown of how your tool compares to LDoc?

I have a few issues with how LDoc does things (or doesn't do things), to the point where I don't bother with it anymore. I don't want to get into it all here, but I'm curious what you think are the most compelling reasons to use your tool instead of LDoc (aside from ease of installation and use; I'm more interested in supported annotations and related features).

LDoc is one I had considered as well and dismissed.

While ease of installation and use lead the way in features, Dox's ability to support user-modified tags is up there too. For example, I have created it to allow both 'func' and 'function' to represent the same tag. Any alias can be added to any tag as desired simply by editing the settings.lua file. New tags can also be added although the process for that is slightly more complicated for function blocks while module info blocks are very easy to modify.

If a particular symbol (such as @) doesn't suit your needs, let me know and I'll add support for the ones people are most likely to use.

I would recommend taking a look at the html files and then looking through the source code at a few comment blocks, that will give you a great example of how Dox works, then, let me know what other features you'd like to see. Keep in mind, this is still in alpha and I have features planned so adding a few more sure wouldn't hurt .

One of the main issues I have with LDoc is lack of support for first-class functions. Actually, this problem is not limited to LDoc or Lua. These doc generators tend to be written as if functions can only exist as members of a class or module, when the language is really much more flexible.

I think an obvious solution to this would be something like a @typedef tag. Its use would look like a @param tag, roughly, except that it would be used in its own block, near the top of the file. It would be used to define complex types (usually function signatures), giving them an alias that can be used as the type in any tags that take a type (@param, @return, and so on). These could be used for stand-alone documentation of callback signatures that might be passed into many functions in a module, for example.

Another thing LDoc can't do, as far as I know, is document functions/methods as having multiple signatures. In Love's API, many functions have multiple signatures, and each one is documented separately. I want to be able to do that with my inline documentation.

Here's my favorite example of something that's nearly impossible to document with something like LDoc: source, readme. The module only exposes a single function, but it makes liberal use of first-class functions. The function exposed by the module returns another function; that needs to be documented. Both of those functions accept callbacks; that needs to be documented. The module passes another function as an argument to the callbacks; that needs to be documented. On top of that, the function exposed by the module and the function returned by that function effectively each have two different signatures, which I'd like to document separately.

I would love to see a documentation generator that doesn't assume everyone only wants to write (or document) class-based or procedural code. It only makes sense to have a doc generator that's as flexible as the language it's made to document.

airstruck wrote:One of the main issues I have with LDoc is lack of support for first-class functions. Actually, this problem is not limited to LDoc or Lua. These doc generators tend to be written as if functions can only exist as members of a class or module, when the language is really much more flexible.

Much agreed. Ldoc makes a lot of assumptions about your code patterns that I find don't always come up in idiomatic Lua (whatever that is). Also, Ldoc does not make it easy and obvious to customize that generated documentation. This is especially a problem with Ldoc because the built-in templates are so ugly.

Well, that's a helluva wish list . But, if I understand you correctly, then Dox already allows for what you want since nothing documented is implicit. All documentation created by Dox is based on how you comment your code. Each function and module are explicitly declared by you. Any functions not declared to be belonging to a specific module are placed in an "Unknown" module.

Dox does not read your code, it reads Dox-specific comment blocks. E.g.

I think all I'd want to be able to do is:

- Define functions that aren't "really there," sounds like you can already do this.

- Use function names as types (in place of built-in string, table, etc.) in other tags.

- Do the same thing with "classes," these could also represent user-defined tables (like "t" in love.conf).

- Define multiple functions with the same name, but different signatures, and have generated docs present that in a sane way.

I suggest trying Dox out and seeing what needs it does not fulfill then let me know and I'll see what I can do.

As far as functions with the same name in the module, I may be able to add that ability relatively easy.

The return type can be anything you type into your comment block so it can easily be a function is you choose it to be. There is no restriction on this whatsoever.

Couldn't get it working, even after supplying the missing "fileFind" on linux. Got it to run, but it didn't put any documentation anywhere. Still looking forward to checking it out whenever that gets resolved.

Linux support is forthcoming but won't be complete for a little while. I'll update here when it's done.

It works perfectly on Windows though. I should note (as is shown on the Github) that this is an alpha release so all planned features may not yet be available.