Page 1 of 1

ZDoc - Automatically generated documentation for PK3s

PostPosted: Sat Nov 17, 2018 4:09 pm
by DavidN
ZDoc in PK3 Tools

Github

My continued safari through Brutal Doom led to me feeling the need for a tool that can make sense of a large ZDoom project's object hierarchy. When projects grow as big as this, classes can be inheriting from each other across different files, you can lose track of what similar classes do if you're coding a lot of special effects, and it can be unclear when flags and properties are being carried over from one object to another. What I've ended up with is a tool that I'm calling ZDoc, which churns through DECORATE or ZSCRIPT and produces an HTML report similar to PHPDoc/JavaDoc laying out the declared classes.

Image

Image

It's available as part of my growing PK3Tools download here, for tools that I hope will help other people develop with GZDoom - it's written in PHP, and a compiled EXE is also provided (though the EXE crashes if you try to use the --resizesprites option, I tried and failed to get the compiler to recognize the PNG library I'm using).

Feature bullet points:
- Takes in a DECORATE or ZSCRIPT folder and optionally a SPRITES folder, inteprets the defined classes and prepares an HTML class tree with individual detail pages for each class.
- Will look for comments above classes in DECORATE/ZSCRIPT with the delimiters /** */ and will include these as class descriptions in the tree and pages.
- Shows when a class extends, replaces or is replaced by another.
- Shows declared and inherited flags/properties for each actor.
- Will highlight when a declaration of a flag or property is redundant, i.e. it's declared in actor code but the superclass would have given it that property anyway.
- Includes cute little icons for each class, if you give it a sprites folder!
- Can optionally just produce the class tree and not all the million other pages

It's used from the command line - to get the usage documentation, run it without parameters. An example use would look like:

Code: Select allExpand view
php zdoc.php --targetdir=./zdoc/ --decorate=../myproject/pk3/decorate --sprites=../myproject/pk3/sprites --resizesprites


This would create a new folder "zdoc" and spit out a collection of HTML pages as it explores the contents of ../myproject/pk3/decorate and sprites.

I'd love it if people were to try this on their own projects to see what happens - my parser is not fantastic just now and I'm thinking of entirely replacing it if one already exists, but it's able to interpret a decent amount. Here are some example ZDoc reports:

BDLite
Doom 2
BDLite and Doom 2 together
Beautiful Doom
Golden Souls 2

Re: ZDoc - Automatically generated documentation for ZDoom

PostPosted: Sat Nov 17, 2018 4:22 pm
by Arctangent
Well, this sure is absolutely badass.

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Sun Nov 18, 2018 12:02 am
by Nash
Yes, my 15,000-line (and growing) ZScript project could definitely use this. Thanks!

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Sun Nov 18, 2018 5:55 am
by sinaptica
That's cool! And more importantly, useful.
Thanks for making it.
Have you considered moving the tools into a separate repository?

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Mon Nov 19, 2018 9:16 am
by Tormentor667
Thanks lot for that, it's of good use!

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Tue Nov 20, 2018 2:09 pm
by DavidN
Thanks! My suite of tools is definitely growing beyond BDLite's scope, I'll probably move them to their own repository and put a frontend on them or something at some point. The parser probably needs some attention first, it's a nightmare of regex that only just about works.

Nash, I'd definitely be interested in if you can get this up and running against your project and to assist with any errors (it's basically tuned to just my Decorate code style just now).

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Tue Nov 20, 2018 5:35 pm
by sinaptica
Cool!
The first thought I had was this could be a great thing to integrate into SLADE, somehow... maybe.

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Wed Nov 21, 2018 8:56 pm
by DavidN
I'd love that :) I'd definitely need some assistance, though - anyone's welcome to pick up what's in the Github and rework it!

Thanks to phantombeta, I've committed and uploaded a new pk3tools.zip with a zdoc that should work much better (i.e. at all) when parsing projects with a heavy amount of ZScript. It's still very shaky, though, and I can already tell that the parser will need to be rewritten from the ground up to get it into a reasonable state (or, preferably, to hook into the parser that ZDoom or SLADE itself uses).

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Thu Nov 22, 2018 4:18 am
by sinaptica
I have not had the time yet to look at the sources.
The first step should be to check what does sirjuddington thinks about all this.
I'll try to read the source this week end and come up with some ideas.

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Thu Dec 06, 2018 4:29 pm
by wolfmanfp
Shouldn't this topic be in Software and Ports category?

Re: ZDoc - Automatically generated documentation for PK3s

PostPosted: Tue Dec 11, 2018 8:06 pm
by Tango
this is unbelievably awesome. thanks so much for releasing it :D