GHOP task #69: document all globals

subscribing

What I currently understand the task to be:

• Find and declare all global variables in a PHP file.
• Add documentation to global variables that are missing documentation
• Complete/Edit existing documentation

Do I modify doxygen to global variables that already have commenting?

A specific question: Is the following considered sufficient for variables such as the one below or should each individual define have documentation?

/**
 *
 * Severity levels, as defined in RFC 3164 http://www.faqs.org/rfcs/rfc3164.html
 * @see watchdog
 * @see watchdog_severity_levels
 */
define('WATCHDOG_EMERG',    0); // Emergency: system is unusable
define('WATCHDOG_ALERT',    1); // Alert: action must be taken immediately
define('WATCHDOG_CRITICAL', 2); // Critical: critical conditions
define('WATCHDOG_ERROR',    3); // Error: error conditions
define('WATCHDOG_WARNING',  4); // Warning: warning conditions
define('WATCHDOG_NOTICE',   5); // Notice: normal but significant condition
define('WATCHDOG_INFO',     6); // Informational: informational messages
define('WATCHDOG_DEBUG',    7); // Debug: debug-level messages

Note: this is chx's task so he has final say over this, but I'll answer to the best of my knowledge to get you going...

Yep, that sounds about right! Bear in mind that we also want to document any functions referenced as globals, so searching for "global " in the source code should give you a nice list ($user is one, for example).

Do I modify doxygen to global variables that already have commenting?

If they don't make sense or are inaccurate, then sure! Otherwise I think you're ok.

A specific question: Is the following considered sufficient for variables such as the one below or should each individual define have documentation?

Nope, each one should have its own doxygen block. You'll notice this looks really odd at http://api.drupal.org/api/constants?page=3.

Nice first catch. :D

functions referenced as globals

By that you mean global instances of objects that functions can be called on and global variables such as $batch?

I have already complete the task as I understood it to be. If this is not what was intended then we can work on getting the intended issue completed.

I went ahead and grouped all the constants using doxygen grouping syntax that provides a nice look in the documentation. When grouping I cleaned up some of the redundant information by putting it once in the group description. I also comment a number of constants that I was able to find and understand their purpose clearly enough to write documentation.

Here are some of the things I found:

• 156 global constants
• I attempted to comment REQUIREMENT_* constants, but was unsure as to the exact function.
• The following constants do not have documentation and I am unsure of their exact function
  • MENU_IS_ROOT
  • MENU_VISIBLE_IN_TREE
  • MENU_VISIBLE_IN_BREADCRUMB
  • MENU_LINKS_TO_PARENT
  • MENU_MODIFIED_BY_ADMIN
  • MENU_CREATED_BY_ADMIN
  • MENU_IS_LOCAL_TASK
  • NODE_BUILD_NORMAL
  • NODE_BUILD_PREVIEW
  • NODE_BUILD_SEARCH_INDEX
  • NODE_BUILD_SEARCH_RESULT
  • NODE_BUILD_RSS
  • NODE_BUILD_PRINT
• The OpenID namespace constants do not appear to point to actual namespace definitions. (not sure if this is intended or they are not meant to point to pages, but interpreted differently)
  • OPENID_NS_2_0 - http://specs.openid.net/auth/2.0
  • OPENID_NS_1_1 - http://openid.net/signon/1.1
  • OPENID_NS_1_0 - http://openid.net/signon/1.0

I hope that my work can be of some use and that we can get this misunderstanding cleared up.

I see that the term variable was used instead of constant and thus my work is probably not what was intended.

Marking for review.

I'd like to add that searching for the keyword global may not get you a complete list. The global keyword provides a way to set global variables from within functions, but any variable set outside of a function is global.

For example, many global variables are set in settings.php. These already have documentation blocks which aren't recognized by the API module, so the exact format of the documentation must be very important.

Besides settings.php, any .php file in the Drupal root directory, the .inc files in the includes directory, and the .module files in the modules directories should be checked for stray globals (globals set outside of functions) that someone may have stuck in there.

I understand the difference between constants and variables since I have done quite a bit of programming and work with PHP. I misunderstood the issue. I see now that it describes documentation of the global variables and not constants.

Not sure how you wish to proceed.

boombatower: What we need a .php file that basically looks like this: http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/hook... but with each global variable (not defines) documented in Doxygen, rather than functions. Basically it would look just like chx's reply in #8, but with all of them, rather than only one.

If this still isn't clear, please post back with specific questions and we'll try and get you on the right track.

I have attached documentation of the global variables instead of constant defines. I was not a 100% sure on some of the variables so there may be a few changes that need to be done. I also was not sure if you would like documentation in other places moved into the global comment blocks instead of referencing it. An example:

/**
 * Active theme object. For documentation of the theme object see _init_theme().
 */
global $theme;

I created a script to find all variables accessed with the global keyword. The script checks for duplicates and creates a blank globals.php file with stubbed out comment blocks. I realize this will not necessarily get all the global variables, but short of searching every file this is the most reasonable list I can come up with.

I hope this is what you were looking for.

Although my previous submission is not what you were looking for I did group the constants that made up enumerations so that the doxygen groups them. I also added documentation to a number of undocumented constants. Not sure if this is of any interest to you.

This looks like it's closer to what chx proposed in the original task. I'm setting the status as needs review to get more eyes on this.

To find the global variables which are not accessed with the global keyword, I would recommend the following process:

1. Copy $GLOBALS to a variable.
2. Include all the .php, .inc, .install, and .module files.
3. Use array_diff_key() to find the new global variables.

• This will not include all the variables since the code may remove them or not instantiate them all. I added the following code to index.php
  

  echo count($GLOBALS);
  print_r(array_keys($GLOBALS));
  

  I got the following result:

  36Array
  (
      [0] => GLOBALS
      [1] => _POST
      [2] => _GET
      [3] => _COOKIE
      [4] => _FILES
      [5] => _SERVER
      [6] => conf
      [7] => timers
      [8] => base_url
      [9] => base_path
      [10] => base_root
      [11] => db_url
      [12] => db_prefix
      [13] => cookie_domain
      [14] => installed_profile
      [15] => update_free_access
      [16] => db_type
      [17] => active_db
      [18] => queries
      [19] => user
      [20] => _SESSION
      [21] => language
      [22] => _REQUEST
      [23] => update_mode
      [24] => multibyte
      [25] => pager_page_array
      [26] => pager_total
      [27] => pager_total_items
      [28] => return
      [29] => theme
      [30] => custom_theme
      [31] => theme_key
      [32] => theme_info
      [33] => base_theme_info
      [34] => theme_engine
      [35] => theme_path
  )
  

  As it says at the top of the attached globals.php file my code found 44 global variables. The $GLOBALS array contains 36 which include some of the PHP system variables.

  The only variable that I did not have is return. I am not sure what the function of that variable is and whether or not you wish to have it documented.

• The addition of the install extension added 24 pages to the search list, but with addition of no globals via the globals keyword search.
• Not sure what to use array_diff_key() on. Are you suggesting I store the array of already found globals somewhere [possibly using var_export()] so that when the script is run again it will only add new variables? I could write that, but at current a simple file compare between a previously generated file and the new file should work fairly well.

I have made the requested changes. Please review them to ensure that I made the correct changes.

Notes:

• $theme - I originally had it as the name, but then I became unsure after i read _init_theme() as you said.
• On $multibyte I was unsure what words to use and thus I guess I left it for later and never fixed it. I added Possible values:
• $item, $element, $tag, $items, $channel - yeah I misread some functions. sorry about that. Also not sure how you want me to link to XML parse so I just link to the starting callback function.
• XRDS I added the phrase you wrote for lack of something better. Not sure if they still need more detail.

I think chx is right about $theme_key being a leftover from the days when $theme was expected to be an object. $theme is definitely the name of the current theme. $theme_key is the same thing.

Frankly we shouldn't be using these globals at all, but using something a little more robust; at the very least, we should be using only *one* global. When Drupal 7 comes around I'll try to work with dvessel to clean that up; it's something that didn't get changed in the last theme system overhaul because I didn't want to figure out where all the globals were used while doing everything else.

The link http://api.drupal.org/api/group/globals/6 in api front page doesn't work.