Task description
This task is to ensure that all functions, classes, methods, and constants in the FAQ and Avatar Selection 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 two 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 2 patches against the 6.x versions of the FAQ and Avatar Selection modules posted to the issue queue that has been reviewed and marked "Ready to be Committed".
Resources
- Drupal Doxygen formatting conventions - http://drupal.org/node/1354
- Drupal Coding Standards - http://drupal.org/coding-standards
- http://www.stack.nl/~dimitri/doxygen/docblocks.html
- http://www.stack.nl/~dimitri/doxygen/commands.html
- FAQ project page - http://drupal.org/project/faq
- Avatar Selection project page - http://drupal.org/project/avatar_selection
Primary contact
Stella Power (http://drupal.org/user/66894 - snpower)
Cheers,
Stella
Comment | File | Size | Author |
---|---|---|---|
#17 | AvatarSelection_FAQ_files.zip | 21.4 KB | andrei.ruse |
#17 | AvatarSelection_FAQ_patches.zip | 8.29 KB | andrei.ruse |
#9 | The_Patches.zip | 32.13 KB | andrei.ruse |
#9 | The modified files.zip | 21.45 KB | andrei.ruse |
#4 | faq_module_documented.zip | 13.26 KB | andrei.ruse |
Comments
Comment #1
aclight CreditAttribution: aclight commentedThis is a GHOP task. See http://code.google.com/p/google-highly-open-participation-drupal/issues/...
Comment #2
stella CreditAttribution: stella commentedClaimed by daryennaruto
Comment #3
stella CreditAttribution: stella commentedClaimed by andrei.ruse
Comment #4
andrei.ruse CreditAttribution: andrei.ruse commentedI have attached the 2 files, zipped, faq.module and faq.install, with the documentation done as much as I could.
I hope everything is alright. I will try to post the other 2 files, avatar_selection.module and avatar_selection.install in 24 hours, in order you to review it until 4th of February.
Comment #5
aclight CreditAttribution: aclight commented@andrei.ruse: Make sure that you create patches for your changes and don't post the full files themselves, as specified in the task description.
Check out the patch creation handbook page at http://drupal.org/patch/create for more information. Or, you can drop by the #drupal-ghop or #drupal IRC channels on irc.freenode.net and one of us can guide you through the creation process.
Comment #6
stella CreditAttribution: stella commentedFYI: I've a rather unfortunately timed trip this weekend. I'm unavailable from 7pm GMT this evening to 7pm GMT Sunday (3rd Feb) for reviewing patches. The deadline is 0hrs PST on the 4th Feb, so I will be around to do reviewing before then. I'll also be available on the #drupal-ghop channel if you want to talk over anything.
Cheers,
Stella
Comment #7
stella CreditAttribution: stella commentedI've reviewed the files, though you do need to create patches as aclight said.
faq.install
faq.module
. Similarly with faq_perm(), faq_access(), faq_menu(), faq_menu_alter() and faq_theme().
Note: indenting of my example comments above don't appear correctly because of the browser display, but there should be one space before the
*
and one after. For @param, etc, descriptions, they should be indented by 2 spaces - that means there are actually 3 spaces between the*
and the description.There are other function descriptions left to review which I will get to shortly. The 6.x version of the coder module is documented quite well if you need an example to compare against while I'm not around.
Overall, the documentation is looking quite good. Keep up the good work!
Cheers,
Stella
Comment #8
stella CreditAttribution: stella commentedfaq.module (cont)
@return $data
would be incorrect.I'm away now until 7pm GMT on Sunday and so won't be able to review your next patches before then. I think if you can fix all of the things mentioned in this and my previous comment, and ensure you don't have similar issues in your avatar_selection patches, then there probably won't be too much to fix on Sunday evening. I'm also sure that there will be other reviewers able to help you this weekend. If you do run into problems or have any questions, I recommend that you join the
#drupal-ghop
IRC channel. See How to use IRC for more details on how to connect, etc.Good luck with the rest of the task and I look forward to reviewing the rest of your patches when I return on Sunday!
Cheers,
Stella
Cheers,
Stella
Comment #9
andrei.ruse CreditAttribution: andrei.ruse commentedI have attached here 2 zip files, one with the modified files, and another one with the patches, as required.
The patches seem a little too big, but since I have never used diff before, I am giving them to you as diff gave them to me:D
I hope everything is OK.
Comment #10
agentrickardThe comments look good but the patches and the files are malformed.
Please format your text files with UNIX linebreaks. These are all DOS-encoded, which is improper.
That explains why your patches are so large. The extra line breaks force the diff to not recognize the original file correctly.
Comment #11
agentrickardFAQ module review:
Line 5 is not needed.
Typo on line 1040-1041.
Remove tabs in the description of faq_block().
Remove apostrophes from FAQs, line 1936.
In general, this is great work.
Comment #12
agentrickardAvatar Selection review.
Line 5 is not needed:
avatar_selection_help() should mention hook_help().
avatar_selection_access() description is hard to follow and does not define $op or $node.
Report the bug in avatar_selection_menu(), please. (Bonus point for that if you know what the bug is!)
Documentation of avatar_selection_handler_filter_role() is wrong. This does not create any roles.
The work on FAQ is better, but these are all easy to fix.
Comment #13
stella CreditAttribution: stella commentedHi,
Back now. I've had a chance to review your work and it's looking very good.
faq.install:
faq.module:
I'll write up a review on the Avatar Selection changes shortly.
Cheers,
Stella
Comment #14
andrei.ruse CreditAttribution: andrei.ruse commentedA couple of questions:
1. faq_settings_page()
* @param $aid // unknown usability
2. _get_indented_faq_terms()
* @param $vid
* Vocab id. - what else than vocabulary?
3. function faq_menu_alter(&$callbacks) - is it an implementation of hook_menu()?
Comment #15
stella CreditAttribution: stella commentedavatar_selection.install
avatar_selection.module
It's looking very good. Just fix these few minor errors and submit new patches before midnight (PST)!
Thanks for all your hard work on this task.
Cheers,
Stella
Comment #16
stella CreditAttribution: stella commentedHi andrei.ruse!
Answers below.
1. faq_settings_page()
* @param $aid // unknown usability
>> this is actually a deprecated / obsolete variable which shouldn't really be there any more. Just say it's a deprecated variable and I'll remove it from the code later this week. Thanks for spotting this!
2. _get_indented_faq_terms()
* @param $vid
* Vocab id. - what else than vocabulary?
>> Your description is correct, it is a vocabulary id.
3. function faq_menu_alter(&$callbacks) - is it an implementation of hook_menu()?
>> No, it is an implementation of hook_menu_alter().
I'm also on the #drupal-ghop IRC channel if you prefer to ask questions there, but here is fine too.
:)
Stella
Comment #17
andrei.ruse CreditAttribution: andrei.ruse commentedAttached:
AvatarSelection_FAQ_files.zip (the 4 files,with the code) - In case the patches are not be ok
AvatarSelection_FAQ_patches.zip (the 2 patches - much smaller than last ones)
Still I have to say that I am not a Linux user (only sometimes, from live distros), and the code was edited in Ms Frontpage & Notepad. That's why the code was nou UNIX-like.
I hope everything is ok with the patches.
Comment #18
stella CreditAttribution: stella commentedThat's perfect! Thank you for all your hard work. All that's left for you to do is to upload the files to the GHOP task on the google tracker - http://code.google.com/p/google-highly-open-participation-drupal/issues/...
Thanks again!
Cheers,
Stella
Comment #19
stella CreditAttribution: stella commentedPatches submitted to CVS. Thanks again.
Cheers,
Stella
Comment #20
Anonymous (not verified) CreditAttribution: Anonymous commentedAutomatically closed -- issue fixed for two weeks with no activity.
Comment #21
stella CreditAttribution: stella commentedFAQ module changes released in FAQ 5.x-2.7 and FAQ 6.x-1.3.
Cheers,
Stella