Hook needed when quiz score is finalized

Well, I just looked at the code, and I'm thinking I may be able to get away with being less invasive.

The long-answer question module calls quiz_update_total_score() to update the score of the quiz when a question is corrected. That calls quiz_calculate_score() which relies on all the question modules to score their own questions. When the modules score questions, they apparently pass back an object with several fields, including one called is_evaluated. That field appears to indicate whether the question was evaluated/corrected. The quiz_calculate_score() function keeps track of it, and the associative array it returns has an "is_evaluated" value that indicates whether all questions were 'evaluated'.

This means that quiz_update_total_score() and quiz_end_actions() can both call the new hook based on the return value from quiz_calculate_score(). If quiz_end_actions() detects that $score['is_evaluated'] is 1 (I'd personally prefer checking for a nonzero value, rather than 1 specifically), it can call the hook. Otherwise quiz_update_total_score() will call the hook later when it checks $score['is_evaluated'].

I am mildly concerned about errant calls to quiz_update_total_score() causing the hook to fire twice for the same quiz (it can happen if it gets called for an already-corrected quiz). I wonder if an extra column in the quiz_node_results table might be useful to indicate whether the results themselves are final. Then that field can just be checked before it does anything. At this point, however, that function only gets called by the long-answer question module, and only when a question is manually scored.

What do you think?

Hmm..as far as I know, grading errors just can't be fixed right now. I haven't noticed such a feature. If it gets offered later, perhaps it might actually be good to re-trigger anything hooking into the grade change.

While I was testing this, I realized there's no real need to invoke the new hook in quiz_end_actions(). This patch only modifies quiz_update_total_score(), and invokes it there regardless of $score['is_evaluated'].

I figure this way, things will seem more sane for module authors implementing these hooks. hook_quiz_finished() will always and only be invoked right when the quiz is finished. And hook_quiz_scored() will always and only be invoked after a question is manually scored (or multiple questions, if they ever get done more than one at a time). In both cases, module authors can check $score['is_evaluated'] themselves to see whether the current score is final:

 function hook_quiz_finished($quiz, $score, $rid) {
  if (empty($score['is_evaluated'])) {
    // the score is not yet final
  } else {
    // the score is final now
  }
}

function hook_quiz_scored($quiz, $score, $rid) {
  if (empty($score['is_evaluated'])) {
    // the score is not yet final
  } else {
    // the score is final now
  }
} 

One final thought is documentation, and I'm also wondering if things could be named better. $score['is_evaluated'] doesn't seem very intuitive.

I was about to generate a patch against the DEVELOPER.txt file, when I noticed that hook_quiz_finished is documented as hook_quiz_finished($quiz, $score) - the extra $rid argument that actually does get passed in isn't mentioned. Is that just an oversight?