January 2007 - Development - lists.drupal.org

Request to be listed as provider of Drupal services
by Alexis Bellido 09 Jan '07

09 Jan '07

Hello, I'd like to be listed as a Drupal consultant in http://drupal.org/drupal-services , I've contributed the following projects: QuickFile: http://drupal.org/project/quickfile An ecommerce oriented module to sell digital download to users who don't need to have a Drupal account. Works with Paypal and Authorize.net and future versions will support other payment processors. Newsletter Checkbox: http://drupal.org/project/newsletter_checkbox A simple add-on to the contact page so that users can mark a checkbox and be added to a newsletter. It currently works with Campaign Monitor's API. This is my user profile: http://drupal.org/user/14007 If after reviewing my case you consider me in the list I'd like to use the following text for my page on the directory: =============================================== I'm a writer and long time peruvian web developer living in Lima, Peru. After running a local based web agency and crafting many websites I decided to incorporate Ventanazul LLC in Florida, United States, in 2004, and start working with customers all over the world. That same year I joined the Drupal community. You can visit my website at: http://www.ventanazul.com/webzine , where I frequently write about web development, technology and Drupal. Some of my Drupal related projects include: http://www.felafacs.org Community site for Federación Latinoamericana de Facultades de Comunicación Social, a Latin America based organization formed by communication faculties of public and private universities. http://www.mumobo.com Personal site with reviews about music, movies and books. http://www.teleworkpeople.com Articles and discussion forum for teleworkers, home of "Telework People", a book I wrote on the subject of working using the Internet. Spanish is my native tongue and I'm quite fluent in spoken and written English. I've recently published the ebook "Drupal en 15 gotas", in Spanish, and am about to finish the English version: "Drupal in 15 drops". The ebook is oriented to web developers and focuses on the installation and administration of Drupal 5. I've contributed two modules to the Drupal community: QuickFile: http://drupal.org/project/quickfile An ecommerce oriented module to sell digital download to users who don't need to have a Drupal account Newsletter Checkbox: http://drupal.org/project/newsletter_checkbox A simple add-on to the contact page that allows users to mark a checkbox and be added to a newsletter. It currently works with Campaign Monitor's API. Services offered: - Installation and configuration of Drupal. - Creation of custom Drupal modules or modification of existing ones. - Web graphics design and porting of your own designs to Drupal themes. - Web standards based design. - Usability consulting. - Internet businesses consulting. Contact: You can use the following contact form to get in touch and discuss your project: http://www.ventanazul.com/webzine/contact ============================================== Thanks! -- Alexis Bellido

1 0

Re: [development] QA: Consensus on comment formatting
by Metzler, David 08 Jan '07

08 Jan '07

IIRC: //* @TODO is also supported by doxygen. The extra * is what gets doxygen to parse it. -----Original Message----- From: development-bounces(a)drupal.org [mailto:development-bounces@drupal.org] On Behalf Of Angela Byron Sent: Monday, January 08, 2007 11:33 AM To: development(a)drupal.org; dopry(a)thing.net Subject: Re: [development] QA: Consensus on comment formatting On 8-Jan-07, at 1:31 PM, Darrel O'Pry wrote: > for phpdoc // @todo wouldn't work... /** @todo would word */ OK. In that case, I'm going to need to -1 @todo. /** stuff **/ as inline comments sucks, because then you can't comment out large blocks of code easily, which is something essential to debugging. That coupled with everyone else saying that // TODO is supported in their editor of choice makes this a closed case, imo. -Angie

2 1

Re: [development] QA: Consensus on comment formatting
by Angela Byron 08 Jan '07

08 Jan '07

Excellent! Thanks for the summary, Derek!! > Here's a new draft of the conventions given everyone's input, my > votes above, and a few other suggestions: > > > * Comments should be written in English, with correct spelling[2], > punctuation, and grammar. > * Being concise is best, but never at the expense of clarity. > * Comments are capitalized and end in periods. They should be > complete sentences on their own line unless they are documenting > lists, or are describing a line of code that only needs a few extra > words to be clear. sentences are separated by a single space.[3] > * @file documentation begins with a sentence in present tense, and > has a blank line before any further comments. > * Function documentation begins with a single sentence in the form > "Do such and such." rather than "Does such and such.", and has a > blank line before any further comments. > * There is a blank line between @param and @return sections in > function documentation. > * Comments should not use all caps, e.g, NOTE. Instead, use @note, > @todo, @warning, @bug, etc. > * Any comment that refers to a variable should include the dollar- > sign in front of the $variable_name. > * Any comment that refers a database table should use {table_name} > to make it visually unique, not "table_name", 'table_name', etc. > * In general, URLs, code snippets, file names, etc, should not be > enclosed in quotation marks (") or inverted commas (') unless it > significantly enhances readability. Where necessary, inverted > commas should be used rather than quotation marks. > * No comment should be, or cause a line of code to become, wider > than 80 characters. > * In general, comments should not refer to issue node ids (for > example, "// This is crazy, and we fixed it in #12345."), since > that's what the CVS annotation and commit logs are for. However, > links to issues are allowed (recommended?) in a @todo or @bug. In > this case, a full URL should be used. For example: > // @todo These queries are very expensive, see http://drupal.org/ > node/105639. > Now, just one (technical) question. Does this: > // @todo These queries are very expensive, see http://drupal.org/ > node/105639. > ...actually work and get parsed by doxygen?? I thought doxygen only worked on function headers. This would make @todo less useful, imo, since: // TODO: this can be an expensive query. Perhaps only execute it every x minutes. Requires investigation into cache expiration. if ($user->uid) { db_query("UPDATE {users} SET access = %d WHERE uid = %d", time (), $user->uid); } Tells me that the queries immediately following that line are expensive, vs. /** * Reads a session variable. * * @todo the update query used here can be expensive.... */ function sess_read($key) { Anyone know? Also, as Robert brought up, // TODO, etc. have support in IDEs (Zend, etc.). Can someone check if @todo does as well? -Angie

6 6

Re: [development] QA: Consensus on comment formatting
by Karen Stevenson 08 Jan '07

08 Jan '07

Speaking as a developer who has probably violated every convention on the list, I think this idea makes a lot of sense, and I think this list nicely sums up all the issues being discussed. Looks like I have a lot of rework to do, so: +1 for being gentle with developers whose modules don't meet these standards : -) Karen ----- Original Message ---- From: Derek Wright <drupal(a)dwwright.net> To: development(a)drupal.org Sent: Monday, January 8, 2007 5:25:19 AM Subject: Re: [development] QA: Consensus on comment formatting +1 for for Angie and Nedjo calling for a standard. ;) +1 for standardizing on @todo, @note, etc as supported by phpdoc/ doxygen[1]. +1 for a newline between @param and @return. +1 for allowing // A little extra clarity. (as a "1-liner") +1 for formatting comments like sentences, but not requiring full sentence grammar on 1-liners. +1 for 80 chars wide if possible. +1 for always referring to DB table names as {foo}, not "foo", 'foo' or foo. Even though it's technically not required as a delimiter since the names can't have spaces, i find it adds a lot of clarity to quickly be able to tell if a comment is talking about the DB at all, and if so, which table(s). Here's a new draft of the conventions given everyone's input, my votes above, and a few other suggestions: * Comments should be written in English, with correct spelling[2], punctuation, and grammar. * Being concise is best, but never at the expense of clarity. * Comments are capitalized and end in periods. They should be complete sentences on their own line unless they are documenting lists, or are describing a line of code that only needs a few extra words to be clear. sentences are separated by a single space.[3] * @file documentation begins with a sentence in present tense, and has a blank line before any further comments. * Function documentation begins with a single sentence in the form "Do such and such." rather than "Does such and such.", and has a blank line before any further comments. * There is a blank line between @param and @return sections in function documentation. * Comments should not use all caps, e.g, NOTE. Instead, use @note, @todo, @warning, @bug, etc. * Any comment that refers to a variable should include the dollar- sign in front of the $variable_name. * Any comment that refers a database table should use {table_name} to make it visually unique, not "table_name", 'table_name', etc. * In general, URLs, code snippets, file names, etc, should not be enclosed in quotation marks (") or inverted commas (') unless it significantly enhances readability. Where necessary, inverted commas should be used rather than quotation marks. * No comment should be, or cause a line of code to become, wider than 80 characters. * In general, comments should not refer to issue node ids (for example, "// This is crazy, and we fixed it in #12345."), since that's what the CVS annotation and commit logs are for. However, links to issues are allowed (recommended?) in a @todo or @bug. In this case, a full URL should be used. For example: // @todo These queries are very expensive, see http://drupal.org/ node/105639. any final changes/editions/subtractions? ;) thanks, -derek [1] http://www.stack.nl/~dimitri/doxygen/commands.html [2] i really don't care about "american" vs. "british" spelling. english sux, but it's the best we've got. :( [3] personally, i find 2 spaces between sentences *way* more readable, but i've already lost that debate (at least a bunch of patches already went into core to force it to 1 space) so i don't intend to re-hash that decision. i'm now in favor of 1 space in comments, just for consistency and less work moving forward.

2 1

QA: Consensus on comment formatting
by Angela Byron 08 Jan '07

08 Jan '07

Hey, folks! In doing a bunch of last minute clean-up patches for the 5.x release tonight with the help of Doug Green's lovely Coder module (http:// drupal.org/project/coder) and ran into the area of comment conformity. Awhile back, Nedjo made a valiant attempt to bring order to the chaos of the way comments are written in Drupal (http://drupal.org/node/ 72240). He lays out some rules there which I think are great and awesome, and seem to fit the way we do things generally in Drupal. However, Dries posted (rightly) that we should come to consensus on this, and document it, before enforcing it. So! Anyone have a problem with these rules: * Comments are full sentences ending in periods. * There is space between %param and %return sections in function documentation (do we want this? sometimes we do it, sometimes not). * Function documentation begins with a single sentence in the form "Do such and such." rather than "Does such and such.", and has a space before any further comments. * Where we have a Note: it is not all caps. * Spelling, grammar, punctuation corrections. And if so, I'll bite you. ;P haha, j/k. No, if so, please make your case as to why one or more of these _shouldn't_ be the way Nedjo specifies here. I'll commit to rolling patches for fixing this, if not for 5.x then for 6.x. -Angie

13 16

Plans for this week
by Dries Buytaert 08 Jan '07

08 Jan '07

Hello world, here are the plans for this week: 1. Release a second (and last?) release candidate. I hope that the final Drupal 5 release will simply be a 'rename' of RC2. 2. Open up CVS HEAD so we can start Drupal 6 development. More about that later, I'll create a new thread for that. It would be great if we could focus all our energy towards the Drupal 5 issue queues for one last time. Drupal 5 is probably going to be _the_ 2007 release and is what many of our users will stick with throughout 2007. Let's make it rock. -- Dries Buytaert :: http://www.buytaert.net/

1 0

Re: [development] QA: Consensus on comment formatting
by Angela Byron 08 Jan '07

08 Jan '07

Excellent! Thanks for the summary, Derek!! > Here's a new draft of the conventions given everyone's input, my > votes above, and a few other suggestions: > > > * Comments should be written in English, with correct spelling[2], > punctuation, and grammar. > * Being concise is best, but never at the expense of clarity. > * Comments are capitalized and end in periods. They should be > complete sentences on their own line unless they are documenting > lists, or are describing a line of code that only needs a few extra > words to be clear. sentences are separated by a single space.[3] > * @file documentation begins with a sentence in present tense, and > has a blank line before any further comments. > * Function documentation begins with a single sentence in the form > "Do such and such." rather than "Does such and such.", and has a > blank line before any further comments. > * There is a blank line between @param and @return sections in > function documentation. > * Comments should not use all caps, e.g, NOTE. Instead, use @note, > @todo, @warning, @bug, etc. > * Any comment that refers to a variable should include the dollar- > sign in front of the $variable_name. > * Any comment that refers a database table should use {table_name} > to make it visually unique, not "table_name", 'table_name', etc. > * In general, URLs, code snippets, file names, etc, should not be > enclosed in quotation marks (") or inverted commas (') unless it > significantly enhances readability. Where necessary, inverted > commas should be used rather than quotation marks. > * No comment should be, or cause a line of code to become, wider > than 80 characters. > * In general, comments should not refer to issue node ids (for > example, "// This is crazy, and we fixed it in #12345."), since > that's what the CVS annotation and commit logs are for. However, > links to issues are allowed (recommended?) in a @todo or @bug. In > this case, a full URL should be used. For example: > // @todo These queries are very expensive, see http://drupal.org/ > node/105639. > Now, just one (technical) question. Does this: > // @todo These queries are very expensive, see http://drupal.org/ > node/105639. > ...actually work and get parsed by doxygen?? I thought doxygen only worked on function headers. This would make @todo less useful, imo, since: // TODO: this can be an expensive query. Perhaps only execute it every x minutes. Requires investigation into cache expiration. if ($user->uid) { db_query("UPDATE {users} SET access = %d WHERE uid = %d", time (), $user->uid); } Tells me that the queries immediately following that line are expensive, vs. /** * Reads a session variable. * * @todo the update query used here can be expensive.... */ function sess_read($key) { Anyone know? -Angie

1 0

Break tag issue compromise
by Karoly Negyesi 08 Jan '07

08 Jan '07

Hi, I suggest a compromise, a variable for the break -- without an interface. To use best, this will need a contrib module to be written but jadwigo already said that such a module could be reused for multipagecontent breaks etc. I believe that such a module would be quite simple. Please give your *thoughtful* review and test http://drupal.org/node/87145#comment-173683 Regards NK

7 6

Project Monitor Module
by Doug Green 07 Jan '07

07 Jan '07

I've made some improvements to the UI of the projectmonitor module (originally version2) based on the initial feedback from this list and one user's experience. The current 5.x-1.x-dev release is now somewhat stable and ready for another round of testing. This version works on both 4.7 and 5. It's working pretty well for me on sites where the contrib modules were downloaded with CVS. I've done much less testing on systems that pull directly from the Drupal release system. While I'm pretty happy with the process of identifying out-of-date modules (.at least on systems pulling from CVS), I'd prefer to provide better "download" links. I think that I'm going to have to use/improve the new Drupal release system to get these. Anyways, I hope I'm moving in the right direction. Doug Green 904-583-3342 www.civicactions.com Changing the world one node at a time!

1 0

Forum Access module
by Earl Miles 06 Jan '07

06 Jan '07

Is there anyone out there with an interest in working to help improve the forum access module? It's a great little toy and something I realize I don't really have the time to commit to continuing along the path that it deserves. 1) One requested feature that I resisted initially but have softened up to is that in the same way that it adds moderators to forums, it could also add user exceptions to forums. Instead of 1 acl attached to the forum it could have 2; the second acl would provide only view privileges, while the first acl provides maintainer privileges. 2) It could really use some better moderation tools. Some API to make it easier to determine if there is a forum moderator and give them tools to actually moderate a forum and not simply give them edit access, which is a start. Obvious tools include some node links to make it easy to unpublish a forum. This might do very well to work with whomever out there is currently maintaing a decent moderation module such that forum access and the moderation module could work in concert (and in so doing allow other forum access-style modules to utilize the same tools) to create a nice suite of tools to make it easy for *whatever* type moderators to do their jobs. Anybody willing to take this up?

1 0