Documentation for `hook_autologout_prevent()` in `autologout.api.php` (and other files) is reversed.

Problem/Motivation

I am working on a website that has several jQuery.post() calls. I found that these were preventing auto-logout from logging out inactive users because these calls would cause $_SESSION['autologout_last'] to be reset/renewed. I searched long and hard and experimented with hacking the module to find out what the problem was and finally came across the API hook, hook_autologout_prevent().

All said and done, I feel that the documentation for the hook isn't very clear nor very easy to understand and may actually be misleading. I spent a couple of hours trying to figure out why implementing the hook and setting the paths called by jQuery.post(POST_URL_HERE) to TRUE calls were STILL causing the $_SESSION['autologout_last'] to be renewed.

Another hour or so later and walking through the code, I discovered that I'd misunderstood and the fix was as simple as switching FROM:

mymodule_autologout_prevent(){ 
  if(in_array(current_path(), array('some-module/some-ajax-path')) { 
    return false;
  }
}

...(the current documentation states that doing the above will "TURN OFF auto-logout" which I took to mean that it'll STOP autologout from resetting its Session timer)...

TO:

mymodule_autologout_prevent() { 
  if(in_array(current_path(), array('some-module/some-ajax-path')) { 
    return true;
  }
}

...(which actually did the trick and stopped my jQuery.post AJAX calls from resetting the autologout Sesssion)...

Proposed resolution

Could we please update the documentation for the hook in question as follows?:

FROM

/**
 * Prevent autologout logging a user out.
 *
 * This allows other modules to indicate that a page should not be included
 * in the autologout checks. This works in the same way as not ticking the
 * enforce on admin pages option for autologout which stops a user being logged
 * out of admin pages.
 *
 * @return bool
 *   Return TRUE if you do not want the user to be logged out.
 *   Return FALSE (or nothing) if you want to leave the autologout
 *   process alone.
 */

TO

/**
 * Prevent autologout from logging a user out. This hook is used to add 
 * the autologout JavaScript files and to determine whether to reset the
 * autologout $_SESSION['autologout_last'] timer counter variable.
 *
 * This allows other modules to indicate whether or not the path of the
 * current request should included in autologout checks. This works in 
 * the same way as not ticking the enforce on admin pages option for 
 * autologout which stops a user being logged out of admin pages.
 *
 * @return bool
 *   <p><strong>Return TRUE</strong>: if the user SHOULD NOT be logged 
 *   out when they are viewing the given path. Set to TRUE, the 
 *   autologout JavaScript files will NOT be added NOR will the
 *   $_SESSION['autologout_last'] variable be renewed. Additionally set the 
 *   return value of your hook implementation to TRUE for paths that SHOULD NOT 
 *   reset the timer. An example of a path that should neither include 
 *   the autologout JavaScript files nor reset the 
 *   $_SESSION['autologout_last'] timer variable would be a passive AJAX 
 *   path that updates some part of the page and as such shouldn't 
 *   extend the autologout timer. If left to FALSE, such calls that are
 *   initiated in time spans LESS than the autologout Timeout Value will have
 *   the effect of the User NEVER being logged out because each call will reset
 *   the $_SESSION['autologout_last'] without needed the Users's interaction.
 *   </p><br>
 *   <p><strong>Return FALSE</strong>: (or nothing) if the users SHOULD 
 *   be logged out.</p>
 */

Remaining tasks

• Creation of patch
• Review by maintainers
• Review by community
• Tests?

User interface changes

No UI changes, is an update meant to assist developers.

API changes

No API changes.

Data model changes

No model changes.