Comments are welcome, but I'm trying to be constructive, so please try to be constructive with me. Thanks
If you'll follow along with me here, on https://www.phpbb.com/extensions/writing/ , as I read through this documentation, I'll explain how I'm understanding/not understanding it here, and I'm hoping that people who do have the knowledge that I'm currently lacking can improve on it, so that I/we can all gain more knowledge today than we had yesterday.
"Writing Extensions" -- ok, I get this section. Looks good.
"How To Write An Extension" --
- Would highly recommend against using GPL license for the demonstration extension, as people are probably pretty highly likely to just grab this and use it as a template for further development. Those of us who are not going to be using GPL, however, pretty much have to not even look at it, lest we potentially be accused of including GPL code within something that has a different license.
- "The example detailed below"..., doesn't actually demonstrate how to write a basic extension that will add a new page to a board. There is nothing of the sort actually detailed below. There are some descriptions of some various concepts, which are probably likely used inside the demo, but very little code is detailed.
- The example of a composer.json is good, however, a link to full documentation on all parameters available, as well as what is required and what isn't required, would be very handy here.
"Extending the Base Class With ext.php" --
- This reads as "Here is a step we're going to describe that has absolutely nothing to do with the demonstration code that we asked you to look at."
- Followed by "this would not be required for most extensions", but for a layman, it kind of seems like it's actually something that most extensions would need -- wouldn't they need to perform some actions upon enable/disable/purge?
- Little description of what the ext.php functions actually do -- we can tell that they are called at enable, disable, and purge. Discussion of the serialised data return. No discussion of what you're actually expected to return from any of these functions, other than at some point, someone wants a "false" response. What does "false" mean? And why the talk of "...when enable_step() is called again"? What causes enable_step() to be called multiple times? "This could be effected by the script redirecting onto itself" .. is it caused by that? or is it caused by some other external thing?
- disable_step and purge_step can be used in a similar way -- similar implies that they are not the same, are they used in the same fashion?
"Controllers" --
- This reads "Controllers can be placed anywhere, can be called anything, and do not have a specific, defined interface to them", "we suggest you put them in a directory called controllers". "A function can be defined, that we call handle(), but you can call it anything you want, which will somehow handle requests to display pages."
- "You don't need to declare standard globals" (duh? why would you declare something that exists already?)
- Immediately after this, the documentation breaks down completely. It goes into the Services and Routing sections, without any sort of description whatsoever, of what we're talking about, a description of anything in the files, the variables that it mentions, these two sections are completely unreadable without significant prior knowledge.
"Including Files"--
- "Here's another section referring to something not at all used in the demo, but you really should use it yourself."
- Paragraph 2 and 3 feels like they are incredibly obvious, which likely means that they need a lot of clarification.
- re: IN_PHPBB. Wouldn't it be so much better to throw in a file in the phpbb include path, that must be required at the top of all files, that simply states
Code: Select all
if(!defined('IN_PHPBB')) exit;
[code]
"Modifying Existing Functionality" -- I thought that's what this entire document was about?
- Core events section: This section doesn't actually describe anything about events, other than that they are somehow located in an "events" directory. Are they php code? data files? There's some talk of some code that is presumably over in that github repository, but without any explanation of it, other than it subscribes to an event (how?) it receives an event variable (but it looks like events do not have a specific interface, ie the variables given to them could be different?)
- Template events: ... i dont' understand this section. I just don't grasp it, other than that it's talking about including css and js.
"Language Files" -- this section looks ok, but doesn't tell you where/how to actually call the function it says you need to call.
"Template Files" -- looks like this section is ok, but could use a link to further documentation.
"Migrations" -- Seems to be missing a large amount about how to actually use something. Documents functions you need. Doesn't document at all how to do anything with it, and little of "why". My guess is that the "why" is the reason why I would think we would want to use the "ext.js" above.
