API.drupal.org: Rework Doxygen comments so people can navigate the comments

I think we're going to need more than this, on all the examples. In the next comment I'll try to write up a bigger list of what I think needs to be done. This is a decent start though - just adding the referral to the install should work.

(I'm not sure whether @see on a file will work)

+++ node_example/node_example.module	10 Apr 2010 02:56:04 -0000
@@ -3,6 +3,9 @@
+ * It is importnat to note that the majority of the functionality for the

important

Powered by Dreditor.

Here's a braindump of what I'm thinking after looking at lots of the examples on api.drupal.org.

1. To be successful working with the doxygen comments, you'll need to set up the API module. Lately this hasn't been too hard, but you need to use the dev versions of api and grammar_parser. Set up using the instructions at http://drupal.org/node/425944. When you have an API site set up, you can just run cron and immediately see the result of your doxygen.

2. Every example group docblock should have at the bottom something like "This example is part of the @link http://drupal.org/project/examples Examples for Developers Project @endlink which you can download and experiment with.

3. Groups are going to be the way that people find their way to the entire example, grouped together. If you take a look at the AJAX Example, which seems to be working the best this way, It has a main group:

http://api.drupal.org/api/group/ajax_examples/7

That lists each of the examples. Then each of those, for example,

http://api.drupal.org/api/function/ajax_example_autocheckboxes/7

shows up in a description and has its own page.

This is done with @defgroup and @ingroup, as you'll see in the AJAX examples.

Doxygen documentation is at http://drupal.org/node/1354.

4. Example groups should be

@defgroup ajax_example Examples: AJAX {

Individual examples should be in a group named like

@defgroup ajax_example_simplest Examples: AJAX - Simplest {

5. We need a master group (Examples) that will be in a main examples.module. The examples.module should be mostly doxy comments that point to the other examples. It will also have a hook_help() explaining its purpose and how to access the other examples.

6. Each example or group should link to its parent group with @ingroup. For example:

@ingroup parent group
@ingroup examples

7. This is a work in progress. We'll have to make some changes when we see how the api docs come out. Let's make sure we get one module correct before proceding. I think the form example is a good place to start. It has 10 examples in two groups (so far).

[Edit: I changed the above a bit based on feedback from jhodgdon.]

I edited #4 to reflect all of jhodgdon's concerns (I think). We talked in IRC and she's reluctantly OK with having lots of new groups.

Here's a first pass at some cleanup on the D7 Form Example. I think the generated docs come out OK. If it passes the bot, I'll commit it and everybody can peruse the results and see if they like them.

HEAD still broken, so I went ahead and committed this one: http://drupal.org/cvs?commit=353976

We'll see what API.d.o looks like in the morning and whether we like it or not.

OK, here's what the D7 Form example looks like after the rework of doxy blocks:

http://api.drupal.org/api/group/form_example/7

Please browse around the 11 examples in the form_example module and see if you think it works.

I didn't make groups for each example. Instead, I just made sure that there were proper @see's in each function.

BTW: HEAD is fixed now.

Here's another pass. This addresses the comments in #11. Just by happenstance I deleted a test (#8) so that will help the ordering.

The most important change in this patch though is that #8 and #9 (the add-more and multistep examples) have been significantly reworked again, per advice from @effulgentsia. Although they're not as general as a real form would be (maybe #8 is) the intent is to show the mechanism.

Committed to HEAD: http://drupal.org/cvs?commit=355264

This will probably need to be backported to the D6 version of the form examples.

Yippee! Go ahead and put it here. There seems to be a never-ending amount of this work, as this project increased in scope much more than we thought.

#4 is the roadmap for what we want to accomplish. There's plenty of work left to do on that in both D7 and D6.

Thanks!

In http://qa.drupal.org/pifr/test/114534, open up the "review log" fieldset to see the patch apply failures. I get the same failures when applying locally. It looks like you might have started with an older version (and didn't pick up the xmlrpc changes that went in on 13 Dec)

Committed, with one small change in page_example (where the hook_help() had been removed).
http://drupal.org/cvs?commit=470470

Thanks so much!

Now, for onward and forward.

@Mile23,

* if you could review the api.drupal.org results with after it gets rebuilt (tomorrow or later)
* Then D7, right?
* Also we can continue this with many other "how to navigate issues" with Examples. Probably, though, when we get api.d.o working the way we want, we can do the other things in other issues.

Thanks!

#29: d7_examples_module_lf_767204.patch queued for re-testing.

And very much appreciated.

I apologize that I've been out of service. Trying to focus on the Git migration and just ignoring this queue. But we'll get your application approved and we should be good to get things committed more often.

So sorry I've been so delinquent on this.

Here's a reroll, which fixes a couple of whitespace issues and removes the CHANGELOG.txt's that were still surviving.

If this survives the testbot please look at it quickly and let's get it in before it kills us. Thanks for all the great work on this, @Mile23 et al.

OK, I committed this, but without the changes to node_access_example.module, because it had a thorough going-over in #947334: Node access example comment; Improve discussion of grants (and there were lots of conflicts)

But here we go!

D7: e652b54
D8: 39ddf0d

Thanks so much for all the wonderful work on this, @Mile23. So sorry it got stuck. Mea culpa.

Thanks TR.

Committed: #55: dc2b847

Sorry, I had missed that this one was hanging out.