Page 1 of 1

Utility Library autodoc oversight

Posted: Thu Mar 20, 2014 5:56 pm
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.

Re: Utility Library autodoc oversight

Posted: Thu Mar 20, 2014 6:03 pm
by ssolie
Bug report has been submitted.

Re: Utility Library autodoc oversight

Posted: Thu Mar 20, 2014 6:15 pm
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.

Re: Utility Library autodoc oversight

Posted: Thu Mar 20, 2014 6:52 pm
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.

Re: Utility Library autodoc oversight

Posted: Sun Mar 23, 2014 3:36 pm
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.

Re: Utility Library autodoc oversight

Posted: Mon Mar 24, 2014 5:17 am
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.