ZDoom Wiki Thread

Discuss anything ZDoom-related that doesn't fall into one of the other categories.

Re: ZDoom Wiki Thread

Postby Blue Shadow » Tue Apr 09, 2019 11:14 pm

m8f wrote:There is a typo in "This article lists no examples" note:
Image

While I'm here, I'd like to thank Phantombeta, Blue Shadow, Bauul, Marrub, and other people who keep the wiki updated. It's very important work.

Fixed. And you're welcome.
User avatar
Blue Shadow
 
 
 
Joined: 14 Nov 2010
Operating System: Windows 10/8.1/8 64-bit
Graphics Processor: ATI/AMD (Modern GZDoom)

Re: ZDoom Wiki Thread

Postby Jekyll Grim Payne » Tue Jun 04, 2019 4:50 pm

Hello there, folks. Ever since I started learning ZScript I've been noticing certain inconsistencies on the wiki, such as argument names not matching their actual names (A_CustomRailgun and A_RailAttack have been the offenders, I've fixed them so far).

My next idea is a bit more radical: change the formatting of the functions. Change it from this:

Code: Select allExpand view
A_RailAttack (int damage [, int spawnofs_xy [, bool useammo [, color color1 [, color color2 [, int flags [, int maxdiff [, Class<Actor> pufftype [, double spread_xy [, double spread_z [, double range [, int duration [, double sparsity [, double driftspeed [, Class<Actor> spawnclass [, double spawnofs_z [, int spiraloffset [, int limit]]]]]]]]]]]]]]]]])


..which has a bunch of basically useless brackets and lacks default values

To this:

Code: Select allExpand view
A_RailAttack(int damage, int spawnofs_xy = 0, bool useammo = true, color color1 = 0, color color2 = 0, int flags = 0, double maxdiff = 0, class<Actor> pufftype = "BulletPuff", double spread_xy = 0, double spread_z = 0, double range = 0, int duration = 0, double sparsity = 1.0, double driftspeed = 1.0, class<Actor> spawnclass = "none", double spawnofs_z = 0, int spiraloffset = 270, int limit = 0)


...which is how it looks in gzdoom.pk3, so imo, no reason for it to look any different on the wiki

It obviously can't be done to all functions overnight, but I think it's a good idea and I'm ready to contribute where I can.


P.S. In addition to that I think we should be adding ZScript examples next to DECORATE examples whenever we can. I've only done it to a few pages so far but I plan to continue.
User avatar
Jekyll Grim Payne
 
Joined: 21 Jul 2008

Re: ZDoom Wiki Thread

Postby NeuralStunner » Tue Jun 04, 2019 9:29 pm

The "useless brackets" are syntax notation for "this is optional", but the way they're stacked is because they're not optional if argmuents after are used. It's a messy situation that can only really be solved by support for named argument calls. (Not sure if ZScript does/will support this. In either case, if not, this is going to need a different approach than just copy-pasting from the PK3.)

Defaults are provided in the argument explanations below. This is especially important in cases where the default is 0, but that value has a special meaning.
User avatar
NeuralStunner
Cuddly but Packin'
 
 
 
Joined: 21 Jul 2009
Location: Indiana, USA
Discord: NeuralStunner#1293
Operating System: Windows Vista/7 64-bit

Re: ZDoom Wiki Thread

Postby InsanityBringer » Wed Jun 05, 2019 12:58 am

NeuralStunner wrote:It's a messy situation that can only really be solved by support for named argument calls. (Not sure if ZScript does/will support this. In either case, if not, this is going to need a different approach than just copy-pasting from the PK3.)
ZScript does support this feature, but with some limitations (they have to be in the same order they're defined in the function definition)

to be quite honest, it has made calling the function in question much, much cleaner. This feature is a good reason to go around and double check that args are named properly on the wiki.
User avatar
InsanityBringer
 
Joined: 05 Jul 2007
Location: opening the forbidden box
Discord: InsanityBringer#9908

Re: ZDoom Wiki Thread

Postby Jekyll Grim Payne » Wed Jun 05, 2019 4:04 am

NeuralStunner wrote:The "useless brackets" are syntax notation for "this is optional", but the way they're stacked is because they're not optional if argmuents after are used.


I know why they are there. It still doesn't seem useful at all to me. The majority of arguments are optional, so I don't see the point of stating that explicitly, and if we provided default values right there, that would imply that you can omit arguments, so that default values are used instead. Also, a complete newbie who opens the wiki for the firt time might not be even familiar with that notation (like I wasn't 12 years ago), and it just confuses them more. So, I don't see the point of those brackets. I do see how they make the thing harder to read. And as for providing values right next to the arguments instead of only providing those below — this would be an obviously huge increase in readability: we'd see all values in one place instead of having to read through descriptions.
User avatar
Jekyll Grim Payne
 
Joined: 21 Jul 2008

Re: ZDoom Wiki Thread

Postby NeuralStunner » Wed Jun 05, 2019 7:31 pm

Jekyll Grim Payne wrote:Also, a complete newbie who opens the wiki for the firt time might not be even familiar with that notation (like I wasn't 12 years ago), and it just confuses them more.
That's how professional language references do it. :shrug:

Newbies wouldn't know that "this = that" makes arguments optional, either. It'd still look verbose and confusing, just in a different way. Ultimately, non-programmers probably shouldn't be trying to learn programming from the language documentation. :P

Mind you, I'm not saying that the brackets aren't messy-looking and annoying on long functions... Just that they're not useless. :P The main issue is making sure the documentation still works for Decorate as well - There are years of live code out there. I think a template - Linking to a page on syntax notation, with a description of how named/optional arguments work, and Decorate limitations - would be the the best way to make the changes work. Reformatting won't mean a thing if it's still not clear how it actually works.
User avatar
NeuralStunner
Cuddly but Packin'
 
 
 
Joined: 21 Jul 2009
Location: Indiana, USA
Discord: NeuralStunner#1293
Operating System: Windows Vista/7 64-bit

Previous

Return to General

Who is online

Users browsing this forum: No registered users and 7 guests