Posted by drumm on December 27, 2008 at 5:41am
http://d6-api.drupal.org/ is like http://api.drupal.org/, but is running on Drupal 6. Please take a look and comment or file issues for anything you find.
I have been trying to make this a basic Drupal 6 upgrade, but more was done:
- Some parser bugs were fixed.
- Basic unit testing was added, with a set of sample code for testing.
- All pages now use themeable templates.
- Minor redesigns have happened throughout.
- Function pages show how a function has changed between branches.
Please file any issues in the API queue.
This is the first public beta of our Bluebeach theme running on Drupal 6, so it needs testing. We do need to continue supporting IE 6, so testing there is especially appreciated. Report issues in the issue queue for Bluebeach.
There are still outstanding issues which will have to wait:
- The regular-expression-based parser depends to much on our coding conventions and does not know about objects. It needs to be rewritten.
- I would like to improve the search block a lot. The autocomplete can be better.
- Awareness of Drupalisms, like special handling theme() and recognizing hook implementations.
- More design improvements, both within the scope of the Drupal.org redesign and beyond.
- Documenting all of contributions.
Comments
Usability of function signature ancestry?
(Posting here instead of an issue because I'm not quite sure how to make this actionable.)
I'm not so sure about this new feature.
a) Its prominence on the page seems misplaced. If I go to a function page, I am going there because I'm generally going there because I'm looking for one of two things: a description of how it works, or an example of how to use it. Now, the first thing my eye gets immediately drawn to is this function signature ancestry, which takes up a huge chunk of space, sometimes pushing the description that I'm actually looking for below the fold.
b) It looks very odd on pages with functions with no arguments and no changes. The first thing I searched for was hook_init(). I was greeted with the following:
4-7 hook_init()
5 hook_init()
6 hook_init()
7 hook_init()
Confused, I wondered if this was maybe another way to navigate to the versions of hook_init() from previous Drupal versions. But none of them are links. I was left scratching my head on what the point of this was before I went back and read this post.
c) Then I clicked on drupal_add_css() which has had a function signature change in Drupal 7. But on the version I'm looking at (Drupal 6) the parameters show in BRIGHT RED which normally signals ERROR CONDITION. I'm left wondering if the function is deprecated in Drupal 6? It also seems buggy because the = 'all' is not in red even though that's been removed as well.
d) The only time I really care about a function signature having been changed is when I'm upgrading my modules/themes. In which case, wouldn't this make more sense as a feature (somehow) to Coder? Or maybe to the handbook pages that describes the code changes between one version and another? I'm not sure, but it definitely doesn't seem to belong in an API reference.
Yes and no ;)
I agree with all of webchick's usability concerns about this new feature. I'll even add one more: it appears that the color-coded diff is only for the D6 to D7 diff, regardless of what version you're looking at. For example, compare:
http://d6-api.drupal.org/api/function/drupal_add_css/5
http://d6-api.drupal.org/api/function/drupal_add_css/6
http://d6-api.drupal.org/api/function/drupal_add_css/7
The only thing that changes between them is which row is bolded and which are greyed out. It seems like the color-coded diff would only happen between the previous version and the one you're looking at.
All that said, I think this is a useful feature, yes, even in an API reference. Yes, all API changes should get mentioned over at the module update handbook page, even if it's adding new API functions (a campaign I've been waging on and off in the core issue queue for years now). However, I think this feature is useful when looking at the API reference for a function for all sorts of reasons...
A) For starters, when you're considering spending time to write your module's code around a given core API, it's nice to get a sense if this has been unchanged for many revisions and is therefore unlikely to change in the future, or if the function signature is different for each version, indicating an API that's still being figured out.
B) Also, it's nice to at least have changes to the function signatures automated, since we can't actually be sure that the upgrade docs are complete.
C) In fact, if this feature was really cool, there'd be a page on the new site that listed all function signatures that changed between any two versions of core, and we could use that to double-check the human-generated (and more readable, prose-added) upgrade docs in the handbook.
...
So, I vote that we keep the feature, if anything, expand it, but I absolutely agree it needs to be much less prominent in the UI. Perhaps a "History of changes" subtab should be added as a local task next to "List references"?
tab sounds good
Agree with all this. If you're maintaining a module which has some kind of support for Drupal 5, 6 and 7 then it's nice to have a quick reference for this I think - but equally it doesn't need to be so prominent.
Keep it
I agree with keeping it. Not sure a tab is best, it could be down on the page below the code example as well, just as another section. I am obviously way more fine with a tab then removing the feature altogether.
Tabs and other comments...
Tabs
Tabs can be vertical or horizontal, and I think a TabNavigator interface works best. When reading/developing, I want to only see the version I'm referencing (aka 6.x), so the others are just clutter and noise to someone skimming docs for the snippet they need to copy-paste.
Function signature at the top
I feel this region should remain near the top and could benefit from an anchor link to the example code block(s).
Multiple code blocks examples
I would also like to say, maybe its time docs allow for multiple example code blocks, but I know that's a fundamental change to how an api module node is built.
less hunting with the scrollbar
Let's consider playing with more links/anchors, fieldsets/groups, maybe even Lullabot's tooltips for quick reference. Imagine shortcut links near the top to jump to different parts similar to Adobe's Flex docs (eg. http://livedocs.adobe.com/flex/3/langref/index.html)
longer list in autocomplete
I'd loooove to see more options, but then again maybe I/we need to be blessed with a better idea.
Chris Charlton, Author & Drupal Community Leader, Enterprise Level Consultant
I teach you how to build Drupal Themes http://tinyurl.com/theme-drupal and provide add-on software at http://xtnd.us
Moving to the bottom would be fine...
And maybe to address the colour concerns, we should colour the version that the signature got changed in only (not the one previous, which you're likely looking at) to something more neutral like yellow or blue.
We still want the function signature at the top of the page
1 reason I suggested another tab is that we definitely want the function signature of the current version of the docs you're looking at prominent and at the top of the page. I thought it'd be confusing to leave that at the top, then have the function signatures again at the bottom with the ancestry. That's why I think a tab is better. But, if there's a good reason to oppose a tab, I'm fine with some non-tab solution so long as:
A) It's not too prominent
B) The current function signature is prominent at the top of the page.
Cheers,
-Derek (dww)
I think it looks fine on the
I think it looks fine on the top but to make it less annoying we could turn off this if there is no change in the function call from current to the next versions. So, that the function change info. only shows up for functions that have actually changed.
I want to do C at some point
I want to do C at some point in the future. There are a lot of interesting things we can do with a big database of code.
background colour for code?
I'm missing the background on the code examples - seems less readable on a white background, but then that might just take some getting used to.
I added a more subtle
I added a more subtle background. A good example is http://d6-api.drupal.org/api/function/t/6.
background colors for tables?
I'm also missing background color for table rows. Also, it is not possible to sort by function name, location, ...
Another thing I noticed is the section "Functions called by" seems to be not correctly populated. Example:
http://api.drupal.org/api/function/custom_url_rewrite_inbound/7/references
http://d6-api.drupal.org/api/function/custom_url_rewrite_inbound/7/refer...
I think the tables need more
I think the tables need more work.
Small tables, like related topics and functions that call/called by, should not be tables. Tables are a lot of visual clutter for one or two related topics.
Big tables, the lists of constants, files, functions, and globals could use a redesign in the future. I think we can do much better than a giant table with a numeric pager. I don't have any well-developed ideas now, but am open to suggestions.
I think custom_url_rewrite_inbound()'s functions call/called by is correct. The bug fixed is http://drupal.org/node/251846.
The signatures beg to be links
As I have working code under all 4 versions currently (yes, even 4.7), I find it excellent to have the 4 signatures be present and prominent. Maybe core devs, who only touch HEAD and the latest stable versions, don't actually have the same needs, which can explain the difference in POV.
However, before even thinking about it, I found myself wanting to click on the signatures to change the current version, instead of going to the top of the page to click on the tabs. It seems these lines, big as they are, are just begging to be turned to links instead of being just plain text.
That sounds like a great
That sounds like a great idea. It also strikes me as the place where links to the nodes about various changes should go. For example, the D6 signature at http://d6-api.drupal.org/api/function/hook_form/5 should link to the D6 FAPI changes. As is, I find it really difficult to deal with documentation both on d.o and on api.d.o, so any integration with change notes would be a huge plus.
Problem with manually added links...
The problem with this suggestion, as nice as it sounds, is that api.d.o is automatically generated entirely by code comments. Only if the PHPDoc itself contained links to d.o handbook pages would something like this be possible. I'm not sure that's a good idea, since the code lives on forever, yet handbook pages edited, reorganized, moved around, etc. So, older versions of the code might point to handbook pages that no longer exist, etc. The only alternative to embedding d.o handbook links into code comments would be to break one of the core assumptions of how api.d.o works and add some mechanism to provide human-generated, manually updated information to associate with any given function reference. I'm not sure that's a good idea, either.
So, as much as I agree it'd be nice to get better integration between api.d.o and the d.o handbooks, I don't see a great way to do that on the api.d.o side of things.
Turn the problem on its head
Regarding handbooks/a.d.o. integration, you make a good point. Handbooks are reorganized more often than a.d.o.. So why not go the other way ? Adding some specific element to the input filter for the handbooks could allow for the definition of reverse links to a.d.o., which the api generator could obtain and merge into the api pages. Along the lines of
At one stroke, we'd have:
Of course, since filters are not context-aware, this would entail not only a filter to display the links, but also submit handler to build the back-links, but it's rather easier than writing a safe filter anyway.
Good idea for the future,
Good idea for the future, but not with new markup. Typing '
l()' into drupal.org should link to the API site. It would need to be a filter module which occasionally gets the function list from a site using the API module.Converting documentation comments into HTML shares a lot with the filter system, there is a chance for using the filter API later.
How is the Forms API page
How is the Forms API page generated? The "Drupal from an OO perspective" page? Those don't look to be generated from code in the same way.
Those come from
Those come from http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/topi...
If they're links, the styling is lost; even more prominent
If the function signatures are links (which duplicate the version switching tabs above), then we basically loose the chance to do any styling/formatting on those function signatures. I suppose we could just make the "5" or "6" into a link, but I'm not sure that'd improve the usability much. And, it still puts all this function ancestry information way too prominent on the reference page.
If I've found the reference page for a specific version of a given function, I want to see (basically in order of importance):
A) the function signature
B) brief summary of what it does
C) description of the expected arguments and the return value it produces
D) full description of the function
E) where the code lives and/or the code itself
F) places that call this code
G) history of changes to this function
By keeping the history of changes at the top, as links, it makes one of the least important things for the reference page basically the first you see, and as links (bold, different color, etc) they're even more eye-catching.
p.s. I'm mostly a contrib developer these days -- I don't spend the majority of my drupal coding time on core itself. I have similar needs of maintaining older versions of contrib. That doesn't explain the differences in how important we see this information. In another comment, I listed some of the reasons I think we should keep this feature, but none of them are as useful for a function reference as the things I've listed in this comment.
Cheers,
-Derek
why would we make the whole line a link?
Who said the whole line should be a link? IMHO making the function name itself a link works nicely. That lets us keep styling of the diff. Also, linking or not does not enforce anything on the placement of the diff.
The subject of the comment I replied to said so...
"The signatures beg to be links"
That's what I was replying to.
Foldable signature box ?
Derek, I think I understand your point, but seeing these signatures next to each other still feels like a real improvement over the existing situation, and moving history to the bottom, as in the G item in your list, loses part of this, IMHO.
Maybe a bit of JS would allow us to have the best of both worlds: keep the signature for the current version at the top, prominent, à la man page, but add some clickable widget to open the list of signatures by version. That way, all signatures could be kept together, but now waste such premium space as the top of reference unless needed. Of course, this could degrade nicely with JS turned off to a situation like the current prototype.
Yeah, that'd also work
Sure, that'd be fine with me. Keeps the clutter out of the way by default for those who don't care -- it's only 1 click for those that do (and doesn't even require a new page load).
If there are no objections to this approach, someone should summarize this and put it as a feature request into the api.module queue.
Thanks,
-Derek
I would like to try making
I would like to try making the function signature changes useful instead of hideable clutter.
Didn't mean to offend...
Sorry if my comments came off to offend your fine work. I've been trying to make clear that I support this feature and think it's useful. However, no matter how useful you make them, they're going to be "clutter" to people who are coming to a reference page for a specific version of a given function to get something done. The historical changes part is really only interesting to a minority of developers at any given time. That's all I'm saying -- most of the time, it's just extra stuff to suck your attention and more data to parse, when all you really want to know is "how does this function work with the version of Drupal I'm currently developing for?"...
I'm not offended, just don't
I'm not offended, I just don't use a lot of words.
Can we have Related function, file or topic block on left side
Can we have Related block on left sidebar it may help to explore more function (hook) with related to current function (hook) ,
for eg. http://in2.php.net/manual/en/function.explode.php here we have list of all string function in left side.
so if someone looking for "_form_alter" then we have list of function related with "form" on left sidebar.
Thanks,
Kuldip Gohil
Feature reuquest
Most non-trivial new features will have to wait. Please file an issue in the API module queue.
Function signatures, 2nd refinement
I made some basic refinements to the function signatures:
Red and green are applied to the variable name- red if it does not exist in the next version, green if it does not exist in the previous version, if both are true, red wins. Further color and maybe algorithm changes are needed.
Hide empty "Functions that call..." / "Functions called by..."
I noticed that this version of api.d.o. does not list the function being consulted in these sections. However, now there may be some of these sections that are empty. Maybe it could be hidden in that case?
Example where section "Functions that call hook_access()" is empty:
http://d6-api.drupal.org/api/function/hook_access/6/references
http://api.drupal.org/api/function/hook_access/6/references
Better, still not ideal, but I give up. ;)
That's better, thanks. If that's how it stays, so be it. I still think it's potentially confusing.
The "4.7 - 5" isn't necessarily self-evident.
On cases where the version has been the same between multiple versions, the link always goes to the latest version, even if you hover over the older version part of the "6-7", etc.
On rows where multiple versions are combined, the row isn't clickable if you're viewing any of those combined versions, even if they would normally link to the latest of them. For example:
http://d6-api.drupal.org/api/function/hook_menu/5
http://d6-api.drupal.org/api/function/hook_menu/6
http://d6-api.drupal.org/api/function/hook_menu/7
On the D5 version, 6-7 links to 7. On both the D6 and D7 version, the "6-7" row isn't clickable at all. I think all of this magic combining and clicking is making it less usable, not more. If we really think people can't find the tabs to switch between versions, let's make that more obvious, but I don't think embedding the links into this table is working.
Frankly, I think we should either have combined rows, or clickable rows, but not both. Trying to make both work is going to be confusing no matter what you do, and it's not really worth the effort. Furthermore, I really think the whole thing is still a little jarring and a lot of information to parse and understand if you just search for a given version of a function and land on the page and want to read the docs on that function.
I still believe the whole thing would be more self-documenting and clear if you had to click on something called "Function history" to see all this historical information. Then:
A) As helpful as it is in some cases, it doesn't get in the way by default the rest of the time.
B) The user has to consciously acknowledge they're looking for the historical changes by clicking on a self-defining link.
I don't at all care if this is another subtab or a JS link to expand a little box, but I think it'd be better.
All that said, I don't care passionately enough about this to continue to advocate for this. I've tried to be clear with my motivation and thought process that's leading to the suggestions. If you don't agree, that's fine. ;)
Cheers,
-Derek
I agree with the version
I agree with the version number concerns, especially if you add in contrib version numbers: 5-1.2 – 6-2.0. I did use an en dash and spaces instead of a standard hyphen.
A row covering multiple versions has to link to one place, so the most-recent is used. Linking to the page itself does not seem useful, so the current version is not linked. The links are not meant to be a primary form of navigation, tabs are still more visually prominent and go to every version.
I'll wait for more feedback before any further changes.
I think it'd be easier if it
I think it'd be easier if it did:
4.7 5, 6 function_foo($bar)7 function foo($bar, $baz)
I find the dash a bit distracting, and when a middle version isn't listed I find myself looking for it.
Having the history on one page suits me though - often I search the wrong version, or follow a link from somewhere which might lead to a different version from the one I want to check - and if I'm only looking for function signatures then it's nice to have them all there.
the search box is too small
try for example "aggregator_a" and see the dropdown..
I was a bit worried about
I was a bit worried about that. http://drupal.org/node/334987
On my screen there's space
On my screen there's space to the right of the search box. It could also be an icon or something to save space.
I made the autocomplete
I made the autocomplete dropdown significantly wider.
I would like a patch for having the search field take up the full available width minus the button. It is currently a fixed size because it is positioned with inline CSS.
api.drupal.ru
Greetings from api.drupal.ru—single localized Drupal API site over the web :)
Nice to see your progress, Neil. New version looks great. Thanks for your improvements and hard work.
I'm planning upgrade our site to D6 in the near future too. I think I can help you with converting things to nodes, because in our case, translation with locale module becomes darn hard to maintain. By the way, we are already converted big pages of docs such as FAPI to nodes and it works like a charm.
No & character
The function signatures don't seem to include the & character before variables that should be passed by reference. For example, compare the testing server's definition of hook_nodeapi with the stable version. I didn't see anyone mention this in the discussion so far.
/ Hannes Lilljequist – SthlmConnection
Good catch, that is quite
Good catch, that is quite the edge case, it had to be the first parameter. Fixed now.
Contrib?
Any chances of getting a contrib-api.drupal.org for the contributions CVS?
Yes, but with that much code
Yes, but with that much code we will need another level of organization: http://drupal.org/node/218306
error
Is the testing finished? The D6 site is unreachable.
There was recently a power
There was recently a power outage which affected some of our servers. The low-priority staging sites are the last to get fixed.
i got search box not working.
hi there!!
i cant find any matches my problem.. i got a search box not working. it does not display or go to any pages (just stay in the same page) however, when i go to "/seach" the page works properly fine.. meaning search box in the search page itself works fine...
any idea, please help me .. thanks!! :))