[drupal-docs] Venting - do not read

[puregin]

Thanks Judah - I can certainly relate to your experiences
in terms of 'where do I start? what's going on here?"
I think that the way you've explained what you're looking
for is very helpful.  I hope that we can use this to make
the documentation more accessible for people who are
jumping in for the first time.

     Djun

On 14 Jun 2005, at 8:22 AM, judah wrote:

>  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
>>
>
>
>> Do you find the introductory sections of the
>> Developer guide useful?
>>
>
>> 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?
>>
>
>> Would a "Start here" page or a "roadmap" to
>> documentation help?
>>
>
>
>  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.
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>