Documentation

Discuss general development subjects that are not specific to a particular version like the versioning control system we use or other infrastructure.
Post Reply
User avatar
callumacrae
Infrastructure Team
Infrastructure Team
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Documentation

Post by callumacrae » Sat Aug 09, 2014 1:59 pm

I've had to guess / ask loads of stupid questions about extensions in 3.1, and now I've got to $request->variable() and I'm having to read the RFC to know how it works.

Either more documentation needs to be written, or it needs to be easier to find.
Made by developers, for developers!
My blog

User avatar
nickvergessen
Former Team Member
Posts: 733
Joined: Sun Oct 07, 2007 11:54 am
Location: Stuttgart, Germany
Contact:

Re: Documentation

Post by nickvergessen » Sun Aug 10, 2014 10:51 am

The doc blocks dont help?
Member of the Development-TeamNo Support via PM

User avatar
callumacrae
Infrastructure Team
Infrastructure Team
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: Documentation

Post by callumacrae » Sun Aug 10, 2014 1:42 pm

You're joking, right?
Made by developers, for developers!
My blog

User avatar
Ger
Registered User
Posts: 270
Joined: Mon Jul 26, 2010 1:55 pm
Location: 192.168.1.100
Contact:

Re: Documentation

Post by Ger » Mon Aug 11, 2014 7:55 am

callumacrae wrote:Either more documentation needs to be written, or it needs to be easier to find.
+1
Above message may contain errors in grammar, spelling or wrongly chosen words. This is because I'm not a native speaker. My apologies in advance.

User avatar
A_Jelly_Doughnut
Registered User
Posts: 1780
Joined: Wed Jun 04, 2003 4:23 pm

Re: Documentation

Post by A_Jelly_Doughnut » Mon Aug 11, 2014 1:46 pm

I'm not going to argue that documentation couldn't be improved (this is a FOSS project after all), but this thread seems quite unhelpful so far in identifying deficiencies. If the docblocks aren't helpful they should be fixed/removed as necessary.

phpbb\request::request::variable() seems straightforward to me. The interface is nearly the same as request_var() in 3.0, except now you can specify REQUEST/GET/POST/COOKIE instead of REQUEST/COOKIE only as in 3.0.
A_Jelly_Doughnut

User avatar
VSE
Extension Customisations
Extension Customisations
Posts: 670
Joined: Mon Mar 08, 2010 9:18 am

Re: Documentation

Post by VSE » Mon Aug 11, 2014 8:18 pm

callumacrae wrote: Either more documentation needs to be written, or it needs to be easier to find.
Sounds like it's time for an official "Documentation Team" :)
Has an irascible disposition.

User avatar
M.Gaetan89
Registered User
Posts: 64
Joined: Tue Jan 28, 2014 7:17 pm
Location: Divonne-les-Bains, France
Contact:

Re: Documentation

Post by M.Gaetan89 » Mon Aug 11, 2014 9:16 pm

I agree with callumacrae.
I have started working on the new version of my website, based on phpBB 3.1. I don't know much about the source code of phpBB, and sometimes it's pretty hard to really know what the parameter are.
If it can help, I'd be glad to make a list of item that does not seem clear to me as I go on with my work.
The problem might be that the people who wrote the docblock knows the source code of phpBB, and thus understand more easily what they are tring to explain.

User avatar
callumacrae
Infrastructure Team
Infrastructure Team
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: Documentation

Post by callumacrae » Tue Aug 12, 2014 11:29 am

The problem with having to rely on docblocks is that they only help if you already know the name of the function.
Made by developers, for developers!
My blog

Post Reply