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 YOUR 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.

ZDoc - Automatically generated documentation for PK3s

Postby DavidN » Sat Nov 17, 2018 4:09 pm

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
Last edited by DavidN on Sat Nov 17, 2018 6:49 pm, edited 2 times in total.
User avatar
DavidN
 
Joined: 28 Dec 2015

Re: ZDoc - Automatically generated documentation for ZDoom

Postby Arctangent » Sat Nov 17, 2018 4:22 pm

Well, this sure is absolutely badass.
User avatar
Arctangent
squawky
 
Joined: 06 Nov 2014
Discord: SquawkyAtan#2371

Re: ZDoc - Automatically generated documentation for PK3s

Postby Nash » Sun Nov 18, 2018 12:02 am

Yes, my 15,000-line (and growing) ZScript project could definitely use this. Thanks!
User avatar
Nash
Nash Muhandes
 
 
 
Joined: 27 Oct 2003
Location: Kuala Lumpur, Malaysia

Re: ZDoc - Automatically generated documentation for PK3s

Postby sinaptica » Sun Nov 18, 2018 5:55 am

That's cool! And more importantly, useful.
Thanks for making it.
Have you considered moving the tools into a separate repository?
User avatar
sinaptica
 
Joined: 31 Jan 2017

Re: ZDoc - Automatically generated documentation for PK3s

Postby Tormentor667 » Mon Nov 19, 2018 9:16 am

Thanks lot for that, it's of good use!
User avatar
Tormentor667
needs more detail
 
Joined: 16 Jul 2003
Location: Germany

Re: ZDoc - Automatically generated documentation for PK3s

Postby DavidN » Tue Nov 20, 2018 2:09 pm

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
DavidN
 
Joined: 28 Dec 2015

Re: ZDoc - Automatically generated documentation for PK3s

Postby sinaptica » Tue Nov 20, 2018 5:35 pm

Cool!
The first thought I had was this could be a great thing to integrate into SLADE, somehow... maybe.
User avatar
sinaptica
 
Joined: 31 Jan 2017

Re: ZDoc - Automatically generated documentation for PK3s

Postby DavidN » Wed Nov 21, 2018 8:56 pm

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
DavidN
 
Joined: 28 Dec 2015

Re: ZDoc - Automatically generated documentation for PK3s

Postby sinaptica » Thu Nov 22, 2018 4:18 am

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
sinaptica
 
Joined: 31 Jan 2017

Re: ZDoc - Automatically generated documentation for PK3s

Postby wolfmanfp » Thu Dec 06, 2018 4:29 pm

Shouldn't this topic be in Software and Ports category?
User avatar
wolfmanfp
 
Joined: 08 May 2017
Location: Hungary
Discord: wolfmanfp#5234

Re: ZDoc - Automatically generated documentation for PK3s

Postby Tango » Tue Dec 11, 2018 8:06 pm

this is unbelievably awesome. thanks so much for releasing it :D
User avatar
Tango
heh!
 
Joined: 31 Jul 2006


Return to TCs, Full Games, and Other Projects

Who is online

Users browsing this forum: Dr.Haxxor and 8 guests