Code comments
Xano - January 4, 2009 - 20:20
| Project: | Services |
| Version: | 6.x-2.x-dev |
| Component: | Documentation |
| Category: | task |
| Priority: | minor |
| Assigned: | Hugo Wetterberg |
| Status: | active |
Description
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.
#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.module
services/menu_service/menu_service.inc (there are headers but they're wrong)
services/node_service/node_resource.* (sporadic)
services/search_service/*
services/system_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.