Utility Library autodoc oversight

Have a question about our Software Developer Kit? Ask them here.

Utility Library autodoc oversight

Postby trixie » Thu Mar 20, 2014 6:56 pm

The current public autodoc for the Utility Library omits description for functions SNPrintf() and ASPrintf() - only VSNPrintf() and VASPrintf() are documented. To add to the confusion, VSNPrintf() and VASPrintf() give code examples that instead use SNPrintf() and ASPrintf(), respectively.
Smoke me a kipper, I'll be back for breakfast!

AmigaOne X5000 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition
User avatar
trixie
 
Posts: 395
Joined: Thu Jun 30, 2011 3:54 pm
Location: Czech Republic

Re: Utility Library autodoc oversight

Postby ssolie » Thu Mar 20, 2014 7:03 pm

Bug report has been submitted.
ExecSG Team Lead
User avatar
ssolie
Beta Tester
Beta Tester
 
Posts: 1010
Joined: Mon Dec 20, 2010 9:51 pm
Location: Canada

Re: Utility Library autodoc oversight

Postby joerg » Thu Mar 20, 2014 7:15 pm

trixie wrote:The current public autodoc for the Utility Library omits description for functions SNPrintf() and ASPrintf() - only VSNPrintf() and VASPrintf() are documented. To add to the confusion, VSNPrintf() and VASPrintf() give code examples that instead use SNPrintf() and ASPrintf(), respectively.
Isn't it the same for all functions with a varargs version, only one version is in the autodoc? In other libraries it's probably only functions with TagItem arguments which have 2 versions, one with a pointer to a TagItem array and the varargs version, (V)SNPrintf() and (V)ASPrintf() may be the only ones not using struct TagItem, but it's still the same.
joerg
 
Posts: 371
Joined: Sat Mar 01, 2014 6:42 am

Re: Utility Library autodoc oversight

Postby trixie » Thu Mar 20, 2014 7:52 pm

@joerg

joerg wrote:Isn't it the same for all functions with a varargs version, only one version is in the autodoc?

It is, but here:
- the autodoc gives no synopsis for SNPrintf() and ASPrintf() at all (looks like the functions don't even exist);
- looking for SNPrintf() under "V" in the functions list is confusing at best - it's different from, for example, AllocSysObject() where both versions are easy to find. For the sake of clarity and logical referencing I'd suggest making a little exception here and providing two separate entries.
Smoke me a kipper, I'll be back for breakfast!

AmigaOne X5000 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition
User avatar
trixie
 
Posts: 395
Joined: Thu Jun 30, 2011 3:54 pm
Location: Czech Republic

Re: Utility Library autodoc oversight

Postby joerg » Sun Mar 23, 2014 4:36 pm

trixie wrote:It is, but here:
- the autodoc gives no synopsis for SNPrintf() and ASPrintf() at all (looks like the functions don't even exist);
- looking for SNPrintf() under "V" in the functions list is confusing at best - it's different from, for example, AllocSysObject() where both versions are easy to find. For the sake of clarity and logical referencing I'd suggest making a little exception here and providing two separate entries.
IMHO replacing VSNprintf() and VASPrintf() by SNPrintf() and ASPrintf() in the autodoc would be enough (with the V* versions added in SYNOPSIS), unlike the non-varags versions of tag functions with a taglist pointer I doubt anyone uses the V*Printf() versions with an args pointer.
joerg
 
Posts: 371
Joined: Sat Mar 01, 2014 6:42 am

Re: Utility Library autodoc oversight

Postby colinw » Mon Mar 24, 2014 6:17 am

trixie wrote:- the autodoc gives no synopsis for SNPrintf() and ASPrintf() at all (looks like the functions don't even exist);


I had the same problem in DOS with Printf() and VPrintf(), people kept telling me the autodoc was missing,
because they were completely different names, so I just duplicated the autodoc and put one under each name,
while mentioning the other in each. It fixed the problem just fine.
User avatar
colinw
AmigaOS Core Developer
AmigaOS Core Developer
 
Posts: 178
Joined: Mon Aug 15, 2011 10:20 am
Location: Brisbane, QLD. Australia.


Return to SDK Support

Who is online

Users browsing this forum: No registered users and 1 guest