[drupal-docs] Venting - do not read

[judah]

puregin wrote:

>On 13 Jun 2005, at 8:59 PM, judah wrote:
>
>  
>
>>Running the contributed modules through phpdoc would be helpful but 
>>they
>>are less document then the core modules. Contributed modules needs some
>>standard requirements for comments like, "You can never have too many
>>comments". I was studying the profile module and there was just a lot 
>>of
>>places where things weren't explained.
>>    
>>
>
>
>  
>
>>I know others have picked it up easily but I haven't been able to. I
>>just heard that drupal generates it's sql statements by using regular
>>expressions. Huh? Where do I learn about this? Also, how do I debug the
>>modules? How do I print out a variable? I would love a something on how
>>to debug and add changes to a specific page. Something like, "So you
>>want to add a feature to a module" tutorial. Or a, "So you want to help
>>debug an error message" tutorial.
>>    
>>
>
>     Have you read the existing tutorial
>
>              http://drupal.org/node/17914
>
>or the "Components of Drupal" and the
>example modules at:
>
>               http://drupaldocs.org/api/head
>  
>
I have now. These have been very helpful. Thank you. For some reason I 
didn't see these before. Are they new? Would it be possible to show the 
authored date or last updated date? That way I can tell if I have read 
this or not. We may need to decouple the "author" from the "author + 
date" line.

>Do you find the introductory sections of the
>Developer guide useful?
>  
>
Yes. This answered a lot of questions. Like I said, I don't know why I 
didn't see this before. A tutorial, "how to debug drupal modules" and 
"how to add features to a module" would still be helpful if only to add 
a few notes pertaining to that subject and then links back to these pages.

>What do/don't you like about the existing Module
>developer's guide?   Drupaldocs documentation?
>
>Do you like to learn the big picture first, and then
>pick up details as you need them, or do you like to
>work out all of the details of one aspect before
>moving on to learn about another aspect?
>  
>
For me, it's better to get a big picture of how it works (possibly in 
the beginning) and then drill down into more detail if I need to. That 
way if I understand a concept I can skip past it. IMHO

>Would a "Start here" page or a "roadmap" to
>documentation help?
>  
>
Definately! Right on the developers section front page. An outline. I 
mean the book module shows an outline on the side but only shows the 
child nodes of the section you are in. The roadmap would guide you 
through what you need to learn one step after another. Including 
semi-related stuff like the theme development, code comments at 
drupaldocs, etc.

You know those kids that when you tell them the sky is blue they ask 
"why?". And then you tell them why and then they ask "why" again and 
again to you've explained as much as you can. That's me. I don't 
normally ask those questions but that's what I'm thinking when I'm 
developing. "Why did they do this? What is this line doing? WHAT THE 
HECK IS THAT?!?! Why are we returning this value? etc etc e plubius ernum"

So for this code I took from the profile module I would love to ask "why".

/**
 * Menu callback; displays the profile field editing form.
 */
function profile_admin_edit($fid) {

  // what is this doing
  if ($_POST['op']) {
    // why are we doing this?
    $data = $_POST['edit'];

    // Validate form:
    profile_validate_form($data);

    // what is this doing?
    if (!form_get_errors()) {
       // what is going on here?
      db_query("UPDATE {profile_fields} SET title = '%s', name = '%s', 
explanation = '%s', category = '%s', weight = %d, required = %d, 
register = %d, visibility = %d, options = '%s', page = '%s' WHERE fid = 
%d", $data['title'], $data['name'], $data['explanation'], 
$data['category'], $data['weight'], $data['required'], 
$data['register'], $data['visibility'], $data['options'], $data['page'], 
$fid);

       // what is this doing?
      cache_clear_all();

       // where does this show up?
      drupal_set_message(t('The field has been updated.'));
       // i can guess what this is doing but tell me to make sure. if it 
is doing something different then tell me why?
      drupal_goto('admin/settings/profile');
    }
  }
  else {
    // what is going on here?
    $data = db_fetch_array(db_query('SELECT * FROM {profile_fields} 
WHERE fid = %d', $fid));
  }

  // why are we doing this?
  drupal_set_title(t('Edit %type', array('%type' => $data['type'])));
  // what does this do?
  print theme('page', _profile_field_form($data['type'], $data));
}

Some of these are obvious to you. Some of these can be explained in the 
drupaldocs. But sometimes they still need explaining for what they are 
doing within the context. Maybe we don't need to comment every line but 
a comment for a set of lines would be great. Something like,
// We check if user has permission, if so add this variable to the user 
table and then save the new info back to the database

Again, I may just need to jump into the support channel and talk to the 
developer.

Best Regards,
Judah

-- 
re·gard
 1. To look at attentively; observe closely.
 2. To look upon or consider in a particular way.
 3. To hold in esteem or respect: She regards her teachers highly.
 4. To relate or refer to; concern: This item regards their liability. 

best
 1. Surpassing all others in excellence, achievement, or quality; most excellent: the best performer; the best grade of ore.
 2. Most satisfactory, suitable, or useful; most desirable: the best solution; the best time for planting.
 3. Greatest; most: He spoke for the best part of an hour.
 4. Most highly skilled: the best doctor in town.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050614/84e22e75/attachment.htm