LöveLëtter - Object-oriented LuaDoc.
Posted: Mon Jan 24, 2011 11:30 am
Hello all lövers,
though Lua isn't technically object oriented, I've been allways using it that way. And because I have also experience with Java and C++, I've always wished to document my Lua code the same way as I did with those languages. But LuaDoc didn't help me very much with it - it was created with structured code in mind and to smuggle classes in, one has to do workarounds like declaring tables named classes or prefixing function docs with class name. But I wasn't satisfied with this.
And, there were other things I thought LuaDoc could do better. For instance, when there's parsing error, you don't want to see the traceback of luadoc's internals, you want to see file name and line number, right?
For all these reasons, I got the idea to start my own documentation tool, one that would do things my way. As a first step, I checked LuaDoc's page to see how hard it would be to alter it the way I wanted. Turned out it's actually quite easy - the authors had it in mind and made luadoc modular. The core part actually just loads files and passes them to 'doclet' and 'taglet', which do the dirty work. So, I started working on my own set of these. And because I'm lazy, I started the easy way - I copied luadoc's default taglet/doclet and began hacking on it.
I called the project LöveLëtter and I've hosted it on github: https://github.com/An00biS/LoveLetter
Right now, it's actually just a proof of concept. The only extra feature is the file/line error message I mentioned above (this bugged me the most).
But what I plan to do is:
* Support declaration of classes and inheritance (that's what it's all about!)
* Make the HTML output look like LÖVE's wiki documentation - because that is object-oriented and it looks just great. This also includes data type declarations with hyperlinks to class definitions.
* Recognize MiddleClass constructs. Because MiddleClass rocks!
Be aware that LL is somewhat complicated to install and use, because I'm creating it the easy way (for me). Check the README for instructions and be patient, I'm working on it.
Hope you like the idea and the implementation doesn't exactly scare you off
Enjoy!
though Lua isn't technically object oriented, I've been allways using it that way. And because I have also experience with Java and C++, I've always wished to document my Lua code the same way as I did with those languages. But LuaDoc didn't help me very much with it - it was created with structured code in mind and to smuggle classes in, one has to do workarounds like declaring tables named classes or prefixing function docs with class name. But I wasn't satisfied with this.
And, there were other things I thought LuaDoc could do better. For instance, when there's parsing error, you don't want to see the traceback of luadoc's internals, you want to see file name and line number, right?
For all these reasons, I got the idea to start my own documentation tool, one that would do things my way. As a first step, I checked LuaDoc's page to see how hard it would be to alter it the way I wanted. Turned out it's actually quite easy - the authors had it in mind and made luadoc modular. The core part actually just loads files and passes them to 'doclet' and 'taglet', which do the dirty work. So, I started working on my own set of these. And because I'm lazy, I started the easy way - I copied luadoc's default taglet/doclet and began hacking on it.
I called the project LöveLëtter and I've hosted it on github: https://github.com/An00biS/LoveLetter
Right now, it's actually just a proof of concept. The only extra feature is the file/line error message I mentioned above (this bugged me the most).
But what I plan to do is:
* Support declaration of classes and inheritance (that's what it's all about!)
* Make the HTML output look like LÖVE's wiki documentation - because that is object-oriented and it looks just great. This also includes data type declarations with hyperlinks to class definitions.
* Recognize MiddleClass constructs. Because MiddleClass rocks!
Be aware that LL is somewhat complicated to install and use, because I'm creating it the easy way (for me). Check the README for instructions and be patient, I'm working on it.
Hope you like the idea and the implementation doesn't exactly scare you off
Enjoy!
