Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Talk:Core APIs

From MoodleDocs
Revision as of 03:28, 6 January 2012 by Martin Dougiamas (talk | contribs)

Some early comments about this list of APIs

  • Surely there is one reason for inventing this, completely bypassing the existing components (both for plugins, subplugins and subsystems). But I cannot really imagine it. Why not use direct mapping between components and APIs ? Code is going to use ones and docs are going to use another?
  • More yet, I don't get why the list of APIs ignores everything that is provided with plugin abilitites. Aren't "auth" or "enrol" or "reports" valid core APIs? In fact I think that the parts of Moodle currently working under the "plugins umbrella" are the most formal APIs we have in codebase (at least the OOP ones).
  • Some of the APIs in the list seem incorrect, inaccurate:
    • database API. it should be split, for sure in ddl and dml APIs at least.
    • time API. => datetime, surely.
    • renderer API => is that really an API
    • upgrade API => WTF is that? I'm specially interested on that, as far as it seems I'm the man in charge of documenting it and I don't know what the hell it is (MDL-30971).
    • grade and grading APIs => Should we have also group and grouping APIs? (sorry, joking, hehe, but don't buy the difference).
    • preference API : set/get/remove_user_preference() functions? Or also config ?
    • admin API ?
    • user API ?
    • install/uninstall API ?
    • ...
    • ...

So, in summary, I don't get which benefits this new list provides, nor I think we are doing well by keeping apart some APIs because of them being "pluggable", nor I think the APIs are well balanced at all. Just my 2cents (really not destructive, but constructive, although it sounds the opposite, guys).

--Eloy Lafuente (stronk7) 05:52, 5 January 2012 (WST)

Hi,

Certainly I agree with Eloy on this one. Why introduce another list of the same API's we already have.
While they look 80% the difference between the code and documentation will cause real confusion for developers learning Moodle, especially in regards to terminology.

I think we need to take great care that we don't come up with new terminology for things within Moodle.
As Eloy noted there are some things in the API list that don't make sense, I've just gone through as part of MDL-30979 and updated the PHP docs for the Output API's. I assume that is what you mean by renderer API, hehe you've confused me with that one?!

Cheers
--Sam Hemelryk 09:48, 5 January 2012 (WST)

i think i also generally share the sentiments above, so here's my general 'exactly!' for the above.

definitely for ddl and dml being mashed together into database API is sad loss of definition. I think theres certainly room for more planned and in depth discussions about our terminologies. not to mention the phpdoc is still not clearly and somewhat agreeably defined in our documentation project where we're implementing this atm.

(whee first talk page comment by me!) cheers!

Aparup Banerjee 00:18, 6 January 2012 (WST)

This new list is for documentation purposes only. We need a new list because NO OLD LIST OF APIS EXISTS! There *is* no table of contents that can group all the main functions available for *PLUGIN AUTHORS*. This started as a subset of get_core_subsystems() and has had things added where necessary.

Getting to specifics from above, based on discussion in HQ this morning and my thoughts:

database -> ddl and dml AGREED, done. time -> datetime Is the reason because of PHPs name? We don't use that name anywhere else? renderer -> output AGREED. Either is fine for me. "Renderer" was what EU people agreed on some weeks ago and it is a bit better for googling, but whatever. upgrade API : It's meant to be everything you can do in upgrade/install (including upgradelib.php and all the tricks we use), and I was thinking it included DDL too. We can leave it until later if required. grade and grading APIs => They are completely separate APIs. The names are a little confusing but I think we need to reuse get_core_subsystems() were possible. preference API : set/get/remove_user_preference() functions, yes. admin API -> Yes, I guess we need to explain settings.php and friends. Thanks. user API -> That's hard to identify. I left it out for now as very few plugins needs to create/edit/delete users. or courses. install/uninstall API -> Don't know about that. install.xml and what else?