Posted by Xano on January 4, 2009 at 8:20pm
7 followers
| Project: | Services |
| Version: | 6.x-2.x-dev |
| Component: | Documentation |
| Category: | task |
| Priority: | minor |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
The latest release hardly features code comments. A lot of functions are not documented well or not at all. Please add a comment block before every function that explains what that function does, what parameters it takes and what it returns.
Comments
#1
You can use the service browser to view the documentation that is written in the service method's .module files.
I'd like to write code comments with the service methods, but then I have to duplicate my comments into the .module files for it to appear on the service browser pages (when I write my own functions). So, for now, I only put them in the .module files.
You probably don't talk about those functions only... but it's something I'm thinking about.
Maybe I'd better post a new issue for that.
#2
I wasn't talking about the service browser, but about real code comments. Developers want to know what every scrap of code does and they want to know it without having to spend fifteen minutes on finding out. Also, api.module depends on those comments.
#3
#4
Wrote some documentation and cleaned out all those unnecessary "@author Services Dev Team" that always irritated the crap outta me.
#5
Oh hell yeah.
#6
I have never been so happy to commit a patch. I had just been planning to do this myself before we released.
That said, there's still a lot of Services that needs doxygen coverage even given this fine work so I'm leaving this issue open so we can track and kill these. A lot will be pretty simple, just token headers for forms and their submit/validate functions. The internal comments could use some work too, but one thing at a time.
Here's what I've found that still needs help:
services_keyauth.*xmlrpc_server.moduleservices/menu_service/menu_service.inc (there are headers but they're wrong)services/node_service/node_resource.* (sporadic)
services/search_service/*services/system_service/*services/user_service/*Everything else looks pretty solid. I'll try and start banging these out unless someone beats me to it!
Thanks again.
#7
I'm adding user_service to this list because, while it has doxygen blocks for everything, they are awful.
#8
I'm releasing this one. I've said my 25kb on the subject ;)
#9
Attached is doxygen for xmlrpc_server.module. Letting the bot have a crack at it before comitting.
#10
#11
OK that one is committed, and I'm committing this one two, which wraps up menu_service.inc
#12
The last submitted patch, menu_service_docs.patch, failed testing.
#13
system_service.inc patch
#14
#15
System service docs committed, here's search service
#16
Search service committed, here's user service
#17
services_keyauth
#18
I'd seriously opt to just commit all of these and then take it from there. Maybe in individual issues?
#19
Actually they've all already been committed, just I've been letting the test bot hit them first. I also like to record every committed patch in an issue for reference when possible.
#20
Haha, heyrocker is awesome.
#21
At this point it is more important to get the release out than clean up the bit that's left. So DONE
#22
Automatically closed -- issue fixed for 2 weeks with no activity.
#24
removing spam tags