Sneak Peak: GDoc

[WhiteDragon]

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.

[Fulg0reSama]

WhiteDragon is attempting to put all GS2 scripters out of business. RUN FOR THE HILLS!

[WhiteDragon]

Originally Posted by Fulg0reSama

WhiteDragon is attempting to put all GS2 scripters out of business. RUN FOR THE HILLS!

Hehe. I'm actually trying to make it easier for people to become scripters by providing easy-to-read documentation!

Edit: Oh, and this may very well be part of my grand scheme to provide script packages along with docs and other resources / conquer the world.

[Soala]

Originally Posted by WhiteDragon

Hehe. I'm actually trying to make it easier for people to become scripters by providing easy-to-read documentation!

Edit: Oh, and this may very well be part of my grand scheme to provide script packages along with docs and other resources / conquer the world.

You only deserve +rep for attempting to help us all.

[Fulg0reSama]

Originally Posted by WhiteDragon

Hehe. I'm actually trying to make it easier for people to become scripters by providing easy-to-read documentation!

Edit: Oh, and this may very well be part of my grand scheme to provide script packages along with docs and other resources / conquer the world.

Riiiiiiiiiight (+rep btw)

[Tigairius]

Nice I will probably use it.

[cbk1994]

Nice work. Someone should take the code you make once you've finished it and generate documentation for some commonly-used objects (TServerPlayer, GuiControl (and children), etc) and upload it somewhere. It would be a valuable resource for new scripters and experienced scripters. I might have a crack at it if no one else does.

EDIT: What are you using for syntax highlighting of the source code? I can provide you with the GeSHi rules I use on my pastebin site if that would be at all helpful to you (example) — even if you're not using GeSHi, you might find the color definitions helpful.

[0PiX0]

I often have trouble finding proper (any) documentation. I'm sure many people do. This seems like it would be very useful. Well done.

[WhiteDragon]

Originally Posted by cbk1994

Nice work. Someone should take the code you make once you've finished it and generate documentation for some commonly-used objects (TServerPlayer, GuiControl (and children), etc) and upload it somewhere. It would be a valuable resource for new scripters and experienced scripters. I might have a crack at it if no one else does.

Yeah, I've thought of this. My first thought was "How do you document an object anyways?", since they are created at runtime and could really be anything. I guess the smartest way to do it would be to create some classes that model the object hierarchy. I would definitely need to get some join() support working to make it as good as it should be though (e.g., generate a graph/tree of the object hierarchy).

And yeah, if you want to do something like this it'd be super cool. It'd also in general be nice to have someone making docs to see if there are any sudden feature requests and stuff. I'm hoping that I'll maybe release a version of GDoc within a couple days.

Originally Posted by cbk1994

EDIT: What are you using for syntax highlighting of the source code? I can provide you with the GeSHi rules I use on my pastebin site if that would be at all helpful to you (example) — even if you're not using GeSHi, you might find the color definitions helpful.

Currently I'm using a Haskell library that reads kate syntax files and highlights accordingly. At the moment I'm just using the Javascript syntax file, but I will probably edit it at some point to match GS2 better.

If you want to send your file my way that'd definitely be helpful so I can see the various tokens you've defined and such.

[cbk1994]

Originally Posted by WhiteDragon

Currently I'm using a Haskell library that reads kate syntax files and highlights accordingly. At the moment I'm just using the Javascript syntax file, but I will probably edit it at some point to match GS2 better.

If you want to send your file my way that'd definitely be helpful so I can see the various tokens you've defined and such.

attached

[adam]

I can see it now, gscript site akin to github and sourceforge, and the ability to pull scripts from rc to your server from it. o.O along with documentation

[Fulg0reSama]

Originally Posted by adam

I can see it now, gscript site akin to github and sourceforge, and the ability to pull scripts from rc to your server from it. o.O along with documentation

Originally Posted by Fulg0reSama

WhiteDragon is attempting to put all GS2 scripters out of business. RUN FOR THE HILLS!

I repeat myself.

[WhiteDragon]

Here is the Haskell source: https://github.com/whitedragon/gdoc. Not really useful if you don't know how to read/run Haskell code but just in case anyone does (afaik only Loriel does).

Updates this weekend probably, can just watch that repo if you are very interested.

[fowlplay4]

The syntax looks mean.

[Crono]

+rep enjoy ur massive boost