while I'm building more code I realize some of the modules are not consistent in using Drupal resources..

- Some modules create menu entries here and there.. do we put all of the in /examples/module? if you have several modules enabled is easier to find if the module does something.

- unless a module defines permissions, examples should be accessed the same way (authenticated or not). If the user requires privileges to access the example functions (forms, pages) in some modules, and not in other, the test files also require the permissions, so they turn into difficult to maintain.

- There is no a module howto referenced in the project page. So, even if using coding styles and coder, a common practice is to split the pages from the main .module, leaving only hooks and required code in the main module file. Not doing this, the example is easier to follow but a -not that good- practice, and doing it may do the example really hard to follow if it is not that big.

- Use of hook_help, own readme.txt or the readme.txt in examples folder? use all?

- others?

Comments

rfay’s picture

rfay
he,him
Primary language English
Location Palisade, CO, USA
commented

Good thinking.

In addition to your thinking, here's my opinion:

  • The *use* of each module should be intuitively obvious, if possible. This might mean:
    • A menu entry, clearly named, and named for the example at hand (so they'll sort properly if multiple examples are loaded, etc.) A naming convention: "Example: Block something".
    • Possibly a main page that explains the use, if necessary.
  • Menu entries should be examples/examplename/whatever
  • I was thinking we should do advanced_help, but I don't want to hold up our basic progress with that. As you say, though, a hook_help would be good.
  • I agree that unless there's some reason, no permissions of any kind should be required to run the module.
  • The main README should have an overview.
  • A README in each module directory should give a quick introduction, including directions if there's anything obscure. For example, in the block example, the demonstration of hooks is not obvious, so perhaps it deserves a mention.

I will update this comment as the conversation continues, and then we can transplant it later.

rfay’s picture

rfay
he,him
Primary language English
Location Palisade, CO, USA
commented

Here are some things ilo and I talked about in IRC tonight:

One general goal: I think we should focus our energies on D7 features that module maintainers are going to need for porting. So DBTNG, Fields, Token, etc. Somebody did a bunch of work on the modules we've inherited a long time ago, but some of them are not so relevant any more. For example, xmlrpc isn't all that important any more. Anybody implementing that should probably be using services module. And the node example module (that does another node type) is hardly relevant since CCK took over the world. It is still useful, but most of the time people should be using CCK.

  • Module intro page: Each module should provide a menu entry with a tiny introduction to what it offers.
  • Menu entries: There should be one main menu entry for each module's examples (which leads to the intro page) and then the other examples can be sub-items.
  • Reference appropriate documentation, including api.drupal.org, drupal.org, and external docs as well. So if there's a decent section in the handbook, point to it.
  • Point out alternate techniques. For example, in the XMLRPC example, mention the services module. In the node module, mention CCK.
  • Primary menu element naming: "XXX Example".
  • PHPDoc is critical, since this will be indexed by api.drupal.org. You probably need to run api module to see what stuff is going to look like. (I may set up a public site for indexing to see how this might work.)
    • Follow Drupal doxygen standards
    • Don't include functions in the group which are really not worthy of being seen in the discussion.

There is an API site with Examples module in it at http://api.dev.randyfay.com.

rfay’s picture

rfay
he,him
Primary language English
Location Palisade, CO, USA
commented

To help us with having feedback on the Doxygen for this module, I set up an API site at http://api.dev.randyfay.com which gets updated whenever there's a checkin (10-minute intervals). That way you can easily look at what you've done and see if it's doing what it ought to do.

rfay’s picture

rfay
he,him
Primary language English
Location Palisade, CO, USA
commented
Status: Active » Fixed

I've added this information to the project page.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.