Utility Library autodoc oversight

Have a question about our Software Developer Kit? Ask them here.
Post Reply
User avatar
trixie
Posts: 409
Joined: Thu Jun 30, 2011 2:54 pm
Location: Czech Republic

Utility Library autodoc oversight

Post by trixie »

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.
The Rear Window blog

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
ssolie
Beta Tester
Beta Tester
Posts: 1010
Joined: Mon Dec 20, 2010 8:51 pm
Location: Canada
Contact:

Re: Utility Library autodoc oversight

Post by ssolie »

Bug report has been submitted.
ExecSG Team Lead
joerg
Posts: 371
Joined: Sat Mar 01, 2014 5:42 am

Re: Utility Library autodoc oversight

Post by joerg »

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.
User avatar
trixie
Posts: 409
Joined: Thu Jun 30, 2011 2:54 pm
Location: Czech Republic

Re: Utility Library autodoc oversight

Post by trixie »

@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.
The Rear Window blog

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
joerg
Posts: 371
Joined: Sat Mar 01, 2014 5:42 am

Re: Utility Library autodoc oversight

Post by joerg »

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.
User avatar
colinw
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 207
Joined: Mon Aug 15, 2011 9:20 am
Location: Brisbane, QLD. Australia.

Re: Utility Library autodoc oversight

Post by colinw »

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.
Post Reply