ZDoc - Automatically generated documentation for PK3s

For Total Conversions and projects that don't otherwise fall under the other categories.
Forum rules
The Projects forums are only for projects. If you are asking questions about a project, either find that project's thread, or start a thread in the General section instead.

Got a cool project idea but nothing else? Put it in the project ideas thread instead!

Projects for any Doom-based engine (especially 3DGE) are perfectly acceptable here too.

Please read the full rules for more details.
Post Reply
User avatar
DavidN
 
 
Posts: 266
Joined: Mon Dec 28, 2015 6:22 pm

ZDoc - Automatically generated documentation for PK3s

Post 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 all

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
Last edited by DavidN on Sat Nov 17, 2018 5:49 pm, edited 2 times in total.
User avatar
Arctangent
Posts: 1235
Joined: Thu Nov 06, 2014 1:53 pm
Contact:

Re: ZDoc - Automatically generated documentation for ZDoom

Post by Arctangent »

Well, this sure is absolutely badass.
User avatar
Nash
 
 
Posts: 17434
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia
Contact:

Re: ZDoc - Automatically generated documentation for PK3s

Post by Nash »

Yes, my 15,000-line (and growing) ZScript project could definitely use this. Thanks!
User avatar
sinaptica
Posts: 19
Joined: Tue Jan 31, 2017 5:41 am

Re: ZDoc - Automatically generated documentation for PK3s

Post by sinaptica »

That's cool! And more importantly, useful.
Thanks for making it.
Have you considered moving the tools into a separate repository?
User avatar
Tormentor667
Posts: 13530
Joined: Wed Jul 16, 2003 3:52 am
Contact:

Re: ZDoc - Automatically generated documentation for PK3s

Post by Tormentor667 »

Thanks lot for that, it's of good use!
User avatar
DavidN
 
 
Posts: 266
Joined: Mon Dec 28, 2015 6:22 pm

Re: ZDoc - Automatically generated documentation for PK3s

Post 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).
User avatar
sinaptica
Posts: 19
Joined: Tue Jan 31, 2017 5:41 am

Re: ZDoc - Automatically generated documentation for PK3s

Post by sinaptica »

Cool!
The first thought I had was this could be a great thing to integrate into SLADE, somehow... maybe.
User avatar
DavidN
 
 
Posts: 266
Joined: Mon Dec 28, 2015 6:22 pm

Re: ZDoc - Automatically generated documentation for PK3s

Post 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).
User avatar
sinaptica
Posts: 19
Joined: Tue Jan 31, 2017 5:41 am

Re: ZDoc - Automatically generated documentation for PK3s

Post 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.
User avatar
wolfmanfp
Posts: 80
Joined: Mon May 08, 2017 11:44 am
Graphics Processor: nVidia (Modern GZDoom)
Location: Hungary
Contact:

Re: ZDoc - Automatically generated documentation for PK3s

Post by wolfmanfp »

Shouldn't this topic be in Software and Ports category?
User avatar
Tango
Posts: 183
Joined: Mon Jul 31, 2006 6:39 pm
Contact:

Re: ZDoc - Automatically generated documentation for PK3s

Post by Tango »

this is unbelievably awesome. thanks so much for releasing it :D
Post Reply

Return to “TCs, Full Games, and Other Projects”