Developer Documentation (Community Wiki Editing)

[My Dime Is Up]

(Cross-Post since I'm not sure which forum to put in. However I think it mostly should be posted here after thinking about it for a little)

A little repost I guess you could say of this https://xenforo.com/community/threads/comprehensive-developer-documentation-for-xenforo-2-0.135567/

I can't explain how dreadful and hard it has been to become an XenForo developer (well for my own community that is; not selling public). There are so many functions that I probably could take advantage of but can't because I have no clue they even exist. And if a function does exist I have to open my Atom, open the entire XenForo 2 install folder, and search through all the files for a specific function. Find where the method is actually declared (not called which fills up the result file list by about 15-50 files) and look at the args and how it works. It's DREADFUL!

As a Garry's Mod developer, or rather you could even reference the PHP guide, I can explore new functions and know how they work with about 1 minute of playing around with the function after looking at the docs (Ex https://wiki.facepunch.com/gmod/debug.getinfo) or for PHP (https://www.php.net/manual/en/function.crc32.php)

If there could be documentation made like Garry's Mod that would be excellent. Every method that is specific to XenForo documented would be great. Obviously I don't expect it instantly, but a start would be very much welcomed. Hey, you would get my addons selling on the website, wouldn't you? Like the Garry's Mod docs, maybe you (the XenForo team) can get basic functions installed, and let the community add to the docs and modify things, so all the work isn't on you.

Anyway, this has always been my major hurtle towards writing something myself. Its what stopped me from writing XenForo addons until about 2 years into ownership of XenForo.

Thanks,

P.S. As a Lua dev, it may seem confusing. I switch between function and method. I mean the same thing, function = method. Sorry!

 

[Lukas W.]

You really wanna get a decent IDE. Basic code editors are nice and all, but just nowhere as powerful. A decent IDE will be able to give you suggestions for functions, hint their function signature while you type them, allow you to jump directly to their definition and that's only a handful of things from a very endless list.

XF is imo structured enough that, once you've familiarized yourself with a handful of basics, you'll know exactly where to look when you need to scout something out. It's very straightforward in terms of where stuff goes, and how it's named. There's a lot of software out there that's struggling heavily with this (looking at you WordPress), where a documentation certainly comes in handy, but I think - while it's ofc never wrong to have one - XF isn't in dire need of a complete code documentation.

 

[My Dime Is Up]

You really wanna get a decent IDE. Basic code editors are nice and all, but just nowhere as powerful. A decent IDE will be able to give you suggestions for functions, hint their function signature while you type them, allow you to jump directly to their definition and that's only a handful of things from a very endless list.

XF is imo structured enough that, once you've familiarized yourself with a handful of basics, you'll know exactly where to look when you need to scout something out. It's very straightforward in terms of where stuff goes, and how it's named. There's a lot of software out there that's struggling heavily with this (looking at you WordPress), where a documentation certainly comes in handy, but I think - while it's ofc never wrong to have one - XF isn't in dire need of a complete code documentation.

I would agree and disagree. As for an IDE, probably should get one (What do you use and recommend especially since I edit over SSH)? As per getting use to XF, it isn't true for everyone though. Not only do I bounce from Garry's Mod Lua to managing the whole Linux dedi and multi-VMs, to my A.P. Computer Science Class in Java, its hard and only the daily developers of XenForo to "get used" how exactly everything works without documentation on a function, its purpose, arguments, and what it returns.

 

[Paul B]

(Cross-Post since I'm not sure which forum to put in. However I think it mostly should be posted here after thinking about it for a little)

The suggestions forum is for the XF software.

Your thread had therefore been moved to the site feedback forum.

 

[Lukas W.]

I would agree and disagree. As for an IDE, probably should get one (What do you use and recommend especially since I edit over SSH)?

Any decent IDE can handle grabbing and syncing files via ssh, but I'd really recommend a local copy. Development and production files shouldn't be mixed.

As per getting use to XF, it isn't true for everyone though. Not only do I bounce from Garry's Mod Lua to managing the whole Linux dedi and multi-VMs, to my A.P. Computer Science Class in Java, its hard and only the daily developers of XenForo to "get used" how exactly everything works without documentation on a function, its purpose, arguments, and what it returns.

I bounce around a lot too, and it really doesn't take all that much work to familiarize yourself with the code. It's not like you have to study and learn everything by heart, just understand the structure.

Also, having everything served in mouth sized pieces has a tremendous influence on code quality imo, and not a positive one. In your example it may not matter all that much as you only use the code for your own site, but some people release their code, and we already struggled enough with quality to have to introduce resource standards.

 

[Brad Padgett]

Most developers these days are using PHPstorm. Amongst other Jetbrains products. Is affordable for the common developer though it's not free unfortunately but you get a perpetual license for $89 which provides updates for 1 year and when the years over if you don't want to keep getting updates you just downgrade to the version that was out when you bought it. You get to keep that version permanently. Personally I'm still learning myself and haven't even fully got a grasp on PHP let alone Xenforo 2 add-ons but I find it's so much easier than it looks if you simply go into your IDE and look at all the files and folders under the src/XF directory. That's where all the magic happens and that's basically all you need to get started on creating an add-on.

You'd be surprised at what you can get done by studying that folder. Everything you need to succeed is in it and by simply reading xenforo 2's functions you will learn easily how to create a class extension properly. I feel like within 2-3 years time by the time Xenforo 2 has grown into it's adulthood I will have learnt everything I need to know. I was self taught for html and css and learned that in about 2 years. As for PHP the best way to learn is to practice. Who says you have to release anything on xf.com at all? Get your local install. Hell, use your licenses allotted test install but set up a way to develop for your own self, rather than for anyone else. If you feel comfortable with an add-on you make, use it on your own site, and if that goes well then release it to the community then and only then.

Atom is a good tool for html and css but when your getting into programming like PHP it's good to have function analysis tools and more detailed error-checking. Jetbrains seems to be the leader in this for now. There are other options available if you do a quick search in google but if you want the best it would be any jetbrains product, ideally storm for PHP. I'm hearing via the dev docs this is even what the Xenforo 2 makers are using to make Xenforo 2 itself.

Lastly, read the available documentation official for Xenforo 2. It might not be as extensive as other docs like Garry's mod according to your post but it lays a foundation to understand the jist of how it's done. Only when you open up src/XF and look at the code itself will you believe me when I say it's all there. Nothing is hidden from your understanding except your willingness to read what's in the folder

 

[Alpha1]

I think complete code documentation would be useful. The current developers docs are a good step forward. Hopefully XenForo will provide comprehensive developer docs in the future.
A wiki could also work:

A Wiki for documentation for developers, webmasters, moderators, end users

What I miss in XenForo is documentation. It would be really useful if there would be a manual for end users, one for staff, developer documentation and more documentation for webmasters. A lot can be found scattered through the forums and resource manager, but due to the nature of forums this...

xenforo.com

 

[My Dime Is Up]

I have setup a clone of my public forums on my local computer and setup Phpstorm (which was easy since I already use IntelliJ Idea). Its excellent, showing me all the functions I can call. It doesn't detail the use of each function and what it returns (obv). A big improvement on my end but I'd still like to see a Garry's Mod-like documentation made where everyone can add stuff that they've found.

 

[Ozzy47]

Anyone can contribute to the developers docs, https://xenforo.com/community/threads/contribute-to-our-xf2-developer-documentation.145585/

 

[My Dime Is Up]

Anyone can contribute to the developers docs, https://xenforo.com/community/threads/contribute-to-our-xf2-developer-documentation.145585/

While yes but it's not a "wiki" of functions, their purpose, arguments, and return values. Primarily function explanation is what we're looking for, not a guide on how to do something specific. Think of this suggestion not as looking for a wiki/guide for being spoonfed information on how to do something or make "your own addon", rather as a wiki/guide on just each individual function.

Wikimedia works great for this (Its what Wikipedia runs) and allows changes to be made and reverted if something was documented incorrectly.

P.S. If you're worried about some just spamming/being toxic on the wiki, the Garry's Mod community is well, I'm not gonna say anything to a large degree, but somewhat more "gamery/toxic" (even the devs) and the wiki has suffered no public destruction at all.)