This is something I've been planning for awhile now, and finally have been able to start in the past few days.
GDoc is an automatic documentation generator for GS2.
You plug in some GS2 code (with docs in it), and it'll dump out a formatted webpage.
Eventually, I want to make it so you can dump in your whole server and get back all your scripts documented. For now, it only works on a single script.
For example, this is the output you get:
http://althack.org/gdoc.html
From this script:
http://althack.org/source.txt
The syntax I use inside the "documentation blocks" is the same as PHPDoc and JavaDoc, so should be familiar to anyone who uses either of those languages. Whenever I finish this I'll write an article on how to write GS2 documentation.
When I extend this to support a serverfull worth of scripts, it will have navigation on the side, and scripts will be separated into npcs/weapons/classes categories.
I'd really like to have some support for showing what classes a script is joined to, but it'd be pretty annoying since it'd involve some heavy GS2 parsing. One possibility is to let the scripter write what classes are joined in comments, but I doubt that'd be updated regularly so I probably won't go that route.
The styling I'm using will likely change in the future, but if there is anything that you'd like to see changed I'm definitely interested.
The code that does this GS2->Doc translation is written in Haskell (a programming language). I'll put it on github eventually, just haven't gotten around to it.
Right now, I have plans to:
- Support parsing an entire serverfull of scripts at once.
- Provide a script-level doc block, so you can give information about the whole script rather than just a function. (I was currently doing it in onCreated but I'd like to separate it eventually.)
- Update the styles some. Not sure exactly what yet.
- (Maybe) Do something about join()s.
This post is basically a request for feedback/comments so let it rip.
01-29-2011, 12:17 AM
Threaded Mode