Hi,

I'm the maintainer of the FAQ, Avatar Selection and Lightbox V2 modules. All three of the modules suffer from incomplete or incorrect doxygen documentation. It's something I keep meaning to go do, but never seem to find the time too.

It would be great if we could have a GHOP task where students can review the API documentation for X contrib modules and write patches to update it. I'd guess you'd need to have specific contrib modules in mind whose maintainers are willing to put in the effort into helping the students and reviewing their work.

In any case, I've 3 modules that need API documentation written and I'm willing to mentor the students and review their work. If this is something you see as a useful GHOP task, let me know and I'll write up a detailed task description.

Cheers,
Stella

Comments

wmostrey’s picture

wmostrey commented

What do you mean with "API documentation"? Is it enough if they put 

/**
 * Implementation of hook_menu()
 */

Do you want more than that? It would help if you could post one or two examples.

If you could take some time to write your request using the task template, that would be great!

stella’s picture

stella commented

Task title
Add PHP documentation to FAQ, Avatar Selection and Lightbox V2 modules

Task description
This task is to ensure that all functions, classes, methods, and constants in the FAQ, Avatar Selection and Lightbox V2 modules have properly formed, complete Doxygen code comments.

Doxygen is the documentation generation system that Drupal uses. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code. The documentation should contain information that is helpful to developers who may not be familiar with the code, such as explaining what functions do, how functions should be called and what information the different parameters contain. Developers often need need to check the API documentation when creating patches or developing new features and so it is important to have clear, correct documentation.

To complete this task, review the three modules and add API documentation to any function, class, method, or constant that does not have it or expand on existing documentation where it is incomplete, unclear, or does not follow established Drupal standards. See the resources section for more information, particularly the "Drupal Doxygen formatting conventions".

The final deliverable will be a set of 3 patches against the 6.x versions of the FAQ, Avatar Selection and Lightbox V2 modules posted to the issue queue that has been reviewed and marked "Ready to be Committed".

Resources

Suggested time
3 days

Primary contact
Stella Power (http://drupal.org/user/66894 - snpower)

Cheers,
Stella

aclight’s picture

aclight commented
Status: Active » Reviewed & tested by the community

I think the description looks good. The only problem is how do we handle this issue in our issue tracker? It will really be 3 separate issues in 3 separate projects.

I guess the best thing is to create a new issue for this task and just use the GHOP project for it. Not ideal, but it's the best I can think of.

If you have a better idea feel free to go with that. The only thing is that we can only put one drupal issue # in the Google issue tracker system, so that's probably the best we can do.

I would say go ahead and taskify this in the google issue tracker. Once you create it, i'll fix the tags and mark it as officially being open.

stella’s picture

stella commented

I was thinking of adding the Coder module (I'm co-maintainer on it). It would push the estimated time to 4-5 days. Do you think that that's too much all in one task?

Cheers,
Stella

aclight’s picture

aclight commented

Well, our limit is actually 1 week for all tasks now just to keep the tracking easier. But remember that 1 day for the students really is probably 1-2 hours. I have no idea about how much code there would be to document, but 4 modules seems like a lot, unless there's little to be done with them.

I'll leave it up to you. You could always just create 2 tasks, each of which included doing 2 of the modules. If you go that way just make sure to create 2 separate d.o issues as well so we can track them separately.

stella’s picture

stella commented

I've created 2 tasks, one for faq and avatar selection (#200879), the other for coder and lightbox2 (#200880). Would someone be able to add me as a member to the Google Task Tracker or post the tasks there for me? I tried opening one for #200879 (GHOP #97) but it won't allow me to set the drupal label, etc.

Cheers,
Stella

stella’s picture

stella commented

aclight: thanks for updating issue 97 for me with the correct labels, would you mind doing the same for issue 101? It corresponds to #200880.

Cheers,
Stella

aclight’s picture

aclight commented
Status: Reviewed & tested by the community » Closed (fixed)

Ok, both issues are all fixed up. I'll mark this as closed to get it out of the way. Thanks for the suggestions!