Posted by hunmonk on December 4, 2006 at 7:24pm
| Project: | API |
| Version: | 6.x-1.x-dev |
| Component: | User interface |
| Category: | feature request |
| Priority: | critical |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
discussion with some fellow devs has led me to explore the idea of making the api module run through the node system -- ie, any api 'objects' (functions, files, constants, topics, php functions, etc.) would be mapped to one object per node.
advantages:
- more robust searching for free: the main documentation would be made the body of the node, so regular searches via search module would provide another search vector.
- comments: users would be able to add comments to further clarify the doc, ala php.net
- bookmarks: using bookmark module, users could have a handy block of links to their most used doc sections.
- ratings/reviews: using voting modules, posted comments could be community moderated by popularity
...and probably half a million other things we get for free, or are easily accessible, because we are interfacing with drupal's primary content system.
disadvantages:
- performance hit: going through the node system could be slower than the current system, which might slow down the doc site for everybody.
- more code to maintain: the module will probably get even more complex if we take this route.
- more site maintainance: if we're installing other contrib modules to get some of the above features, then it will be more maintenance/upgrade work for the api.drupal.org folks.
i'd like to get some feedback on this idea, and if it seems well loved, then i'll look at tackling it. :)
Comments
#1
+1 from me. I was one of the "fellow devs"
It might make code more complex, although I have a feeling it could also just as easily simplify it, since we can re-use a lot of bits that node module takes care of for you (display and such)
#2
Yes I think this will be a good idea. I have been asked with the E-Commerce api that people be able to enter in comments, which would add an additional level of documentation.
#3
subscribing. i'd love it. one of the best things about php.net... actually make that the only good thing about php.net's documentation is the comments.
#4
You know, I could stand to learn a bit more about api internals.... Grabbing. (and developing against DRUPAL-5--1 because it's all like newer than HEAD and stuff.)
#5
For the record I am not completely sold on this. The previously-mentioned disadvantage, "more site maintainance: if we're installing other contrib modules to get some of the above features, then it will be more maintenance/upgrade work for the api.drupal.org folks," is most relevant for me. Additionally, I would like to see most bugs cleaned up before any change like this, they are more important.
#6
Yeah, I kept running into things that should be fixed first. Unassigning myself...
I think a good long look at filtering would be a good idea. There's some stuff that happens during display that makes me uneasy.
#7
Officially setting to postponed.
#8
Subscribing. I'd like to try to hammer this out.
#9
I think it is extremely important to implement commenting on the api. I can't tell you if this is the best solution or not, but I think that would be greatly beneficial to all drupal developers.
#10
+1 for me also. Getting in comments would be very useful.
#11
Yet another big +1 here (and subscribing). drumm and bdragon, are the bugs you're referring to in #5 & #6 pretty much what's in the issue queue right now, or are there other outstanding issues that don't currently have issues filed?
#12
Oh right, the feedback part :)
I think/hope that the switch over to nodes wouldn't mean TOO much additional maintenance for the module maintainers, but I may well be talkin out of my ass there. In any case, I think the potential added utility from comments in particular is enormous, php.net being the perfect example of why. From the user standpoint it's already been said, but the comments that are added are often invaluable when it comes to exploring edge cases, finding workarounds for common problems, or simply filling in where the documentation itself fails, as drewish points out.
It's not just users who would benefit from the comments, though. I think there's also tremendous potential added benefit from a developer's standpoint. People are going to post things in api comments that they're unlikely to put in an issue queue (I certainly wouldnt') - ruminations on how the API works, pieces they wish were just slightly different, data/processes they had to write icky workarounds to get access to, etc. I see that as a potential gold mine for Panels (we'd need #253363: Support classes and class methods first, but anyway), because as it stands, only a very small handful of people feel comfortable approaching me or merlin for a chat via IRC are really able to share those kinds of thoughts in an off-the-cuff way. I don't really want that to change - that sort of synchronous communication is rough on time-management - but I would like there to be a way where I can be 'asynchronously' aware of a wider breadth of people's thoughts & experiences in implementing the API. With that kind of information:
And hey, since it's not sitting in my queue, I don't HAVE to respond to it - everything's just take-it-or-leave-it. Perfect.
All this gets me thinking about a tangentially related possibility: #256963: Panelize api.module?
#13
I'm in for this.
As a starting drupal developer I'm breaking my head out to find examples or to put some of my hard working braincellfunctions back on the web. This would improve the development of the drupal code and have a better view on how to use the code...
Actually.. I really need this
+1 for me...
#14
An interesting bridge approach to this would be to implement Views 2 integration against the api tables (api_documentation as a base table in particular) and replace much of the existing query / UI / menu callbacks with default views. This would eliminate a great deal of code and would then provide an easy transition (swapping out Views base tables, handlers, etc.) to API node objects when it is ready.
I may begin Views 2 integration against the existing API architecture if this sounds promising.
#15
Views doesn't get us comments or ratings which are the biggest wins of moving to nodes.
#16
+1 for getting comments.
Is it an insane dirty hack to consider adding a column to the comment table and using it to get comments without going through the node system?
Or another approach: comments ARE nodes, with a field to attach them to the relevant api page.
Should 'Allow comments on API pages' be a separate issue from this?
#17
+1 on comments from me, too.
#18
I think this needs a serious look at whether nodes are necessary or not. Nodes is not really the goal, comments are; it is likely nodes are required for this, but maybe not. Recent changes for Drupal 7 are making APIs unique to nodes more usable across Drupal and the make-everything-a-node era may be coming to an end. I want to keep the goal up-front instead of implementing random APIs for the sake of more APIs.
This is still postponed, there are gaping holes in documentation, like objects, and the comment parser is a bit more shaky than I would like, it needs unit tests.
#19
This is true, but nodes would have other benefits as well. For example a "flag as incorrect", the ability to categorize and tag functions, the ability to add CCK metadata, etc.
The idea of implementing a reply system to duplicate comment.module in order to get away from treating API objects as nodes strikes me as heading down the same path as our old project_issue module, which we put tremendous work into migrating *away* from that to standard nodes/comments.
#20
Categorizing and tagging should happen in documentation comments. Documentation should be in-code unless there is an incredibly good reason not to.
Flag as incorrect should be opening and pre-filling an issue against Drupal core.
I fully agree with not re-implementing comment module. Nodes are likely a good way to go, but I want to make sure comments get implemented in the best way possible, which likely involves nodes. Comment module has a few improvements to be made in core, which I think might be moving, so more options might become available.
#21
I have just added this to the list of ideas for SOC2009, as I don't think that it will be hard but I do think that it will have real benefit to the project.
#22
gordon: Can you link to the list?
#23
Yes, It is just apart of the basic outline document. see http://groups.drupal.org/node/18127#project-ideas-thinkers
I would also be happy to mentor this, and I would also include this issue as a part of the project as I feel the final implementation would not be too hard to add the additional code to a module to have comments implemented.
#24
No new modules should be made just for commenting.
Do make sure you keep the API project and me informed of API-related SoC projects. A year or two ago someone made SoC projects for API module and I didn't realized the projects had been done until after SoC was over (I am better at reviewing this issue queue now). I will likely be available as a mentor.
#25
Agreed, I see that implementing commenting into a new object should be less then 50 lines of code. I actually think it should be even less than that.
The adding of comments to the user object, I am not sure if that would be able to be committed into core, but I at least a patch will be available as a proof of concept to do this.
Not only would there be a patch submitted to the API module to allow it to have comments on an object, I would also get the Student to implement comments onto transactions for e-Commerce.
Most likely 1 part of the project would be an investigation of contributed module and which would benefit from allowing comments to be added.
Also this would not break existing comment extending modules like comment upload and others and if it does to submit patches/possible solutions to fix the issue.
I know that this man be difficult as a lot of these modules like API have not been ported to Drupal 7. I see the biggest part of this project is actually going to be interacting with the community to get all this worked out.
Gordon.
#26
I have created a a project proposal http://groups.drupal.org/node/20312
#27
A big yes please from me. I was just talking to some people last night about this very thing and would love to see it happen. I'm more than willing to help out if/when it is needed.
#28
#29
more! now functions, constants and globals, too.
#30
On the content admin page you can delete if you really want to using multiple delete (the edit link simply redirects back to the page :) ) and now I keep the documentation records in sync with this.
#31
Delete used the wrong table thanks Dmitri.
#32
Delete is gone and not needed as the db_rewrite_sql will take care of it.
#33
subscribing.
#34
I heard some wanted an update function. Sure. Added uninstall too.
#35
I will release the new version of api.drupal.ru on 1 of June. It will include comments, bookmarks, content localization and other useful stuff that are already exists for Drupal. How did I done this? I made it as a node-over-api-page. And yes, it still will be able to reindex whole bunch of branches. These took 16 hours to code everything with 3 lines of code changed in core API module itself.
Still reinventing the wheel?
#36
Wow, really good good good news! A new era has arrived! Can you please help with the api.drupal.org to make it the same if that's possible?
#37
Possibly, yes.
#38
Referring to #24 above about "API-related SoC projects"
The new grammar parser (possibly with a plug-in to to parse the Doxygen comment block items) will suffice for parsing and providing the information needed for this project.
See also #300031: Rework PHP parser.
#39
#500536: File an issue for this link needs to be solved in the same release cycle as this.
#40
Must happen in next release.
#41
Committed.
#42
Automatically closed -- issue fixed for 2 weeks with no activity.
#43
For how many people wanted this, http://groups.drupal.org/node/25461 sure is inactive. The only response to the call for webmasters even said she didn't want comments. I had to beg in IRC for someone else to try posting a comment. I hope I didn't overestimate the community's desire for this feature. I have gotten a couple good patches fixing obvious bugs in the feature, so someone is looking.
#44
By the way, at api.drupal.ru I implemented comments two months ago. Site has 1K visitors per day, but for 2 month there are only 10 comments were created. It's really sad thing, as I got tons of requiests for comenting before, but nobody is actually commenting when ability has been given.
#45
drumm, don't blame people for not noticing something you hid over on g.d.o. people subscribed here so you should have announced it here (sooner). i keep checking api.drupal.org expecting to see the ability to comment. how would i have known to goto http://d6-api.drupal.org/ ?