Give more detailed examples of hook_perm inside of page_example.module

Note: for D7 the hook is actually hook_permission() and it takes different arguments for the array returned. So, do you think I should create permission_example for D7 instead of creating perm_example?

Here are the .info and .module for the D6 version. At least this way you can take a peek if you want and provide feedback.

I know that I still need to roll this properly as defined in create cron_example. I also know that I have not changed my editor configuration for the line endings as requested.

@hutch. Thanks for rolling the patch. I actually have a bit more I want to add to the module.

I changed notepad++ to use Unix line endings. I added and committed the new module, and ran the diff against origin to get the attached patch file. However, I get warnings the LF will be replaced by CRLF. So, I still don't know if I've got things right. Also, coder_tough_love doesn't like what I'm doing the @see lines. Take a look and see if you are okay with it.

First off, I will admit that I hadn't looked at the page example. I've had a look at it now and it does provide some detail about hook_perm.

I know that I didn't think to look in the page_example module to see if it dealt with hook_perm. So, I wouldn't expect others to look at it to learn about permissions. But, maybe people do generally look through all the examples when they download the project. Somehow, I got it into my mind that the modules were named like hook_example, when in fact that isn't the case in general. On the contrary, it seems to be the case only for the modules I have been trying to add to the project and (sort of) for menu_example.

So, if you think that page_example is the most logical place to give details about hook_perm, then I think I should update page_example to include the things I put in this module.

Does that seem like a good course of action?

Also, what is your thought about my use of @see http://api.drupal.org/api/drupal/developer--hooks--core.php/function/hook_perm/6 and [how] would you like to see it used in the other example modules?

Edit: I see that http://api.drupal.org/api/drupal/developer--hooks--core.php/function/hoo... explicitly references page_example.module. So, I guess that answers my question about whether it's the most logical place.

Edit: According to Mile23 the appropriate way to add the hook references is NOT to use @see http://api.drupal.org/. . .. So, I think I've got my answer on that question.

Actually Mile23 said I should use @see hook_whatever() and doxygen will insert the appropriate link. The modules already [should] have Implements hook_whatever(). Many of them still say Implementation of hook_whatever(). But, I am already planning to get all that stuff cleaned up. Regardless, I am not seeing a link to the appropriate api included in the module itself. I don't think that's going to happen when I use @see either. My point is that people may not know about api.drupal.org and it would be good to point them to it explicitly in the module itself. Also, I must admit that I don't even know (for sure) where I'm supposed to go to read the doxygen comments. I thought that the doxygen comments are what create the documentation on api.drupal.org.

Are you suggesting that maybe we create index.module? I can take on that task as I'm going through this enhancement / cleanup process.

I've got notepad++ set to use Unix EOL. But, this seems to trigger a warning in my Git Bash that says LF will be replaced by CRLF. So, I don't know how the patch is going to come across.

This is the patch that was supposed to be attached above.

Assuming you are happy with the above patch, I'll need to update the .test file. Agh! The patch failed anyway. Let me get that cleaned up.

I cleaned up to two exceptions. The fail results from the fact that I have changed some text that the .test is asserting. So, I have changed the .test file to assert the proper text. I have also added the other tests. I've got to install simpletest for D6 and check that everything is running okay.

But, what order are we supposed to do things now? The test file has changed and the module has changed.

I've still got to get the .test and the .module cleaned up a bit more.

What I'm really getting after with the @see (or whatever you think I should use) is that I want people who are looking at the code in the examples project to see the link to the api.drupal.org page. IMO, it's not about what api.drupal.org does with things (to create links). It's about the fact that I don't think we can assume that beginning developers even know about api.drupal.org. Hence my desire to explicitly point them to it in the documentation of the example modules.

So, for example [once I get all this straightened out], for the D7 version of the page_example.module in the spot where I am giving a more detailed explanation of hook_permissions() I would tell them to see http://api.drupal.org/api/drupal/modules--system--system.api.php/functio.... Similarly, in whichever .module and at whichever point we are illustrating a given hook we will point them to the page on api.drupal.org. We will choose just one place to do this; we won't do it with every use of the hook across all the modules.