| Author |
Message |
|
|
 Posted: Apr 29, 2008 - 05:28 AM |
|
Joined: Jan 23, 2004
Posts: 7014
Location: Melbourne, Victoria, Australia
|
|
Hi Freaks,
I'm busy fixing up the API for configuration descriptors for the next release of my MyUSB library. However, I've designed two different APIs for the interface processing.
One does not need to know anything about USB to take part in this poll. I simply want to know the general consensus on which API is the "better" one - which code seems more readable.
"API 1.c" shows the current API (slightly extended from the 1.3.2 config descriptor API. "API 2.c" shows the new API I was just working on, which uses comparator "plug-in" functions to search for specific descriptors. The latter API requires a little more flash space (45 bytes in a real world application) but allows for much more flexibility than the first.
Which API should be in the final version? You decide.
- Dean  |
_________________
Last edited by abcminiuser on Apr 29, 2008 - 09:20 AM; edited 1 time in total
|
| |
|
|
|
|
|
|
Posted: Apr 29, 2008 - 05:56 AM |
|
Joined: Sep 14, 2003
Posts: 4209
Location: Queanbeyan, Australia
|
|
I do very much like the semi-pluggable search thing you've got going on in the second API. That said, I reckon you've got too many layers of obfuscation in there. I mean:
[code]DESCRIPTOR_SEARCH(NextHID)[/quote] What does this generate? What will the function be called? How do I call it? I 'spose if I were using the library I'd be in a position to find the definition of DESCRIPTOR_SEARCH, work out what it's doing then go back and expand the macro in my head etc. As a complete outsider; what's the matter with a real function definition and me knowing what it's all about at first glance?
(As a side note, this style of definition works well for ISRs, but IMO doesn't work well outside of that)
A comment about both bits of code though, IMHO it's a little overcommented. Your function names are good enough that I can read them and get the same (if not more) information than I can from the comment the line before. If anything the comments make it a little harder to follow the flow of execution! 
-S. |
_________________
Blag: http://www.niasdigital.com/blag
|
| |
|
|
|
|
|
|
Posted: Apr 29, 2008 - 09:34 AM |
|
Joined: Jan 23, 2004
Posts: 7014
Location: Melbourne, Victoria, Australia
|
|
|
Quote:
I do very much like the semi-pluggable search thing you've got going on in the second API
So do I. It takes a few more lines than the first, but is *far* more flexible. It's designed for host applications, and all the host-supporting USB AVRs have at least 64KB of flash, so the extra <100 bytes won't impact anything too much.
Quote:
What does this generate? What will the function be called? How do I call it? I 'spose if I were using the library I'd be in a position to find the definition of DESCRIPTOR_SEARCH, work out what it's doing then go back and expand the macro in my head etc. As a complete outsider; what's the matter with a real function definition and me knowing what it's all about at first glance?
That's what the documentation is for! I agree it's not the best solution, but neither is having the user supply their own complete prototypes -- it looks neater to use the macro like I do for the event hooks. The only downside is having to refer to the library for the current parameter list for each event, but all comparators will have identical prototypes.
Quote:
A comment about both bits of code though, IMHO it's a little overcommented.
I've commented the hell out of the MyUSB demos, so that everyone can benefit from looking at them. Experienced coders can either ignore or strip out the comments, but I see no harm in helping the newbies.
Thanks for the input. Anyone else want to voice their opinion on this?
- Dean |
_________________
|
| |
|
|
|
|
|
|
Posted: Apr 29, 2008 - 01:47 PM |
|
Joined: Jan 23, 2004
Posts: 7014
Location: Melbourne, Victoria, Australia
|
|
I think API 2 is the way to go. Attached is the same functionality as in the API 2 example, but shows off the power of the flexible comparison functions.
Makes for much more readable/reusable code, IMHO.
- Dean |
_________________
|
| |
|
|
|
|
|
|
Posted: Apr 30, 2008 - 03:42 AM |
|
Joined: Jun 21, 2002
Posts: 676
Location: Canberra, Australia
|
|
I'll go for 2 - it looks more flexible
C.H. |
|
|
| |
|
|
|
|
|
|
Posted: Apr 30, 2008 - 08:09 AM |
|
Joined: Jan 23, 2004
Posts: 7014
Location: Melbourne, Victoria, Australia
|
|
Since the new API was partially dependent on the old, I ended up using and documenting both. All the MyUSB demos use the new API however, as that's the one I like the best.
The Mass Storage Host code was simplified quite a bit by the new API, and even compiled down to a slightly smaller size!
- Dean |
_________________
|
| |
|
|
|
|
|
FAQ •
Search •
Register •
Log in to check your private messages
Log in
• 
Minimize
• 
RSS
