search

jtackaberry / luadox

Lua API documentation generator
Apache License 2.0
15 stars 2 forks source link

[FR] @todo and @fixme tag to include bug tracking in documentation #2

Open MathieuCGit opened 3 years ago

MathieuCGit commented 3 years ago

Hello Jason,

Thanks a lot for your huge work, I just finished my migration from LDoc tu Luadox and I'm very happy with it !

So, here is a feature request I'd like to suggest, in LDoc we got the ability to use @fixme and @todo tags directly into the code, which let devs the possibility to point / to pin issues and track them (but yes, it was quite tedious to get those symbols in a usable list).

Could it be possible to create this kind of behaviour as we could use such tags and have an auto-generated list of references (file name, lines, comments) it would really help to document issue.

regards

jtackaberry commented 3 years ago

Sure @MathieuCGit, should be easy enough to add. Do you think the LDoc approach of having a --tags command line argument to list specific tags is sufficient, or do you have other ideas on how it should work?

I'm very glad to hear that you've had a good experience migrating from LDoc. I am actually surprised anyone stumbled upon LuaDox this early -- I haven't done any promotion because the project of mine that prompted my writing LuaDox isn't out yet, and I had wanted to use it as a proper demo before promoting LuaDox better. I guess you found it on page 5 of Google or something? :)

I'm keen to learn about any pain points or other observations about your initial experience.

Thanks!

MathieuCGit commented 3 years ago

So, I thought of something very simple. a tag like @todo or @fixme could be use anywhere in the lua file and look like :

--- @todo add a cool functionality here or --- @fixme this should return 42 but doesn't work, we have to fix this part.

and your script would parse this and generate 2 other main sections in the documentation as shown here : luadox-improvement_TODO-fixme

This could really help if, for example, we have futher files with a "@fixme issue with 42" , this way, in a simple array, we could see all the references to this particular issue.

In the same idea, I'm coding some stuff only when I have the time and not as a professional programmer, sometimes it takes a long time before i can return to coding and a simple look at the TODO let me refresh my brain and obviously let me share the tasks with other interested peoples easily.

Not as powerfull as a bugtracker, but ideal for small project.

And I come to luadox not from google but beacause I'm a big fan of reaticulate and I'm trying to code a script for reaper. So I'm studying your code, learning from the best is always a good idea :)...event if I won't use such complicated stuff like class....speaking of, I wonder, is there any luadox generated documentation for reaticulate ?