Arguably the most important function in the Moodle API, is the create_course function. One would think... after all Moodle is an LMS. Courses are the bread and butter for course management platforms, right? Taking a look at the function in the course/lib.php file reveals almost nothing about the function! WTF? ... btw, the function starts at line 3260

/**
 * Create a course and either return a $course object or false
 *
 * @param object $data  - all the data needed for an entry in the 'course' table
 */
function create_course($data) {
    global $CFG, $USER;
    /** omitted for your sanity */
}

Wow, I think I know less about this function now than before I went digging into the code. How do I assign a teacher to my new course, how do I populate the data object it takes as a parameter (is there a course setup function)? Since courses aren't really objects in Moodle (just glorified arrays), am I just supposed to set them up by hand... $object->param = val?  Are there default values and/or required attributes that need to be set, otherwise my program is going to come to a halt? What about student enrollments? No example to help for how one might actually use this function? Do I have to really read through the code, starting at around line 3260, then jump between the rest of  this monstrous 4000 line piece of spaghetti coded file and try and make sense of it works (somehow).

How is it possible that the most important function (since the core problem Moodle solves is creating courses) in the entire application has no meaningful documentation? I think I have an answer. The entire code base is soooo convoluted and a giant waste of CPU cycles, that it would too embarrassing to actually document how it even works.

Just finishing up brewing up some fresh ground comments...