where to document additions to the core API?
with all the excitement around $node->body (which i share -- way to go, everyone!), and looking over http://drupal.org/node/64279 ("Converting 4.7 modules to 4.8/HEAD") i stumbled into a question that i don't have a good answer for, and no one in #drupal seemed to know at the time, either: in 4.8, i added a new function to the db_* API, db_table_exists(), which is a portable way to find out if a given table exists in your DB (i wrote mysql and pgsql versions). it's a potentially handy method, especially for certain hook_update_N() operations if you have to deal with some special/weird cases (what i wrote it for in the first place), but i'm not sure it's relevant to document it in #64279, since it's not really specific to "converting 4.7 modules to 4.8". nothing is potentially broken by this addition, no one *has* to know the new function exists, etc. it's *certainly* not CHANGELOG.txt worthy. however, if not in #64279, how are developers supposed to know about new functions in the API like this? 1) assume they follow all the core cvs commits closely? ;) 2) spam this mailing list about it and hope everyone who might like to know is subscribed? 3) ignore it completely -- if folks need a function like this, they'll pour through the source or the doxygen and find it (assuming it's named something intelligent). do we have a place to document additions to the API like this? do we need a sub-page off of #64279 for additions that aren't specific to updating? am i being crazy, and this should just go directly into #64279, after all? ;) thanks, -derek (dww)
2) spam this mailing list about it and hope everyone who might like to know is subscribed?
Didn't you just do that? ;-) Anyways ... You correctly note that this has no migration impact. Isn't it enough to just add doxygen comments for it, and it will end up in api.drupal.org eventually? It would not hurt to keep a list of those and announce on the development mailing list periodically. Perhaps as they come in, and once when 4.8/5.0 is released for a consolidated list.
Khalid B wrote:
Isn't it enough to just add doxygen comments for it, and it will end up in api.drupal.org eventually?
Should be within an hour. -- Neil Drumm http://delocalizedham.com/
am i being crazy, and this should just go directly into #64279, after
is is perfectly reasonable to put new developer functionality into the updating page. this is our chance to tell module developers how they can improve their modules with our new widgets. you will notice that new features are already there such as hook_profile_alter().
On Aug 10, 2006, at 6:14 PM, Moshe Weitzman wrote:
is is perfectly reasonable to put new developer functionality into the updating page. this is our chance to tell module developers how they can improve their modules with our new widgets. you will notice that new features are already there such as hook_profile_alter().
sounds reasonable to me, thanks. -dww p.s. http://drupal.org/node/64279#db-table-exists ;) p.p.s. khalid, yes, i did spam the devel list about this trivial function (twice), but only as an example to illustrate my question. ;)
participants (4)
-
Derek Wright -
Khalid B -
Moshe Weitzman -
Neil Drumm