First draft of the modules doc

[afilina]

Q	A
Documentation	yes
Bugfix	no
BC Break	no
New Feature	no
RFC	no
QA	no

Description

I followed the recommended Module section as per this outline.

• Intro: gives a relatable explanation of how modules might be used.
• Structure: the file and directory structure mimics the skeleton app instead of the original example, otherwise new developers will be confused.
• Loading: since the outline mentioned composer, I described the steps to register the module and autoload the namespace.
• Configuration: I'm not sure what to put here. It sounds like we need a section to describe the array config, but then some of it might overlap with other parts of the docs. I need more guidance.
• Listeners: a new section that I added to describe how to add methods such as getConfig() and getModuleDependencies() to the Module class. I only have an into and one listener. I'll wait for feedback before doing the rest.
  • I want a code example for each listener, because otherwise we are left to guess what the method should return.
  • I include the interface in the example, as it seems easier to read this way, as opposed to mentioning it in a paragraph somewhere.
• Best Practices: this could be mostly the current content of "Best Practices when Creating Modules". We can also keep it as a separate page like it is currently.

We'll obviously need to remove some redundant sections from other pages, or even entire pages.

[afilina]

@froschdesign I have a few questions:

1. Configuration: It's a section from your outline. I'm not sure what to put here. It sounds like we need a section to describe the array config, but then some of it might overlap with other parts of the docs. I need more guidance.

2. Best Practices: this could be mostly the current content of "Best Practices when Creating Modules". We can also keep it as a separate manual page like it is currently, and just link to it.

3. Also, are we ok with my current approach to document listeners? Can I do the rest the same way?

[froschdesign]

1. Configuration: It's a section from your outline. I'm not sure what to put here. It sounds like we need a section to describe the array config, but then some of it might overlap with other parts of the docs. I need more guidance.

The outline is only a draft, so changes are possible at any time and improvements even more so.

2. Best Practices: this could be mostly the current content of "Best Practices when Creating Modules". We can also keep it as a separate manual page like it is currently, and just link to it.

👍

3. Also, are we ok with my current approach to document listeners? Can I do the rest the same way?

Did you see the hints @Xerkus gave in the chat?

[Xerkus]

I'll review it a bit later. A lot of things become obsoleted or not recommended.

[Xerkus]

Suggested change

	A module is a PHP namespace. It can contain controllers, classes, view scripts, configuration, tests, as well as public assets such as images, CSS, and JavaScript. For example, if you have an e-commerce application, you could have a module for presenting and selling products, and another for administrators to create products and manage orders.
	A module is a package of logically grouped resources in PHP namespace. It can contain controllers, classes, view scripts, configuration, tests, as well as public assets such as images, CSS, and JavaScript. For example, if you have an e-commerce application, you could have a module for presenting and selling products, and another for administrators to create products and manage orders.
	Strictly speaking, for the application module is defined by the class `Module` in module namespace which is responsible for providing configuration necessary to setup the application. No assumptions are made about file or code structure.

[Xerkus]

There are two conflated concepts. A module that is a package in module/ and a module that is configuration provider referenced from modules list.

[Xerkus]

I think this is mostly irrelevant tbh. It was intended mostly to provide module loading order for configuration merging. I never seen it actually used outside of few edge cases. Config provider used by mezzio does not have or need such feature at all.