TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
In a syntax summary -- what if one argument is a list of name-value pairs?
Subject:In a syntax summary -- what if one argument is a list of name-value pairs? From:David Castro <thetechwriter -at- yahoo -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 23 Jul 2002 08:41:11 -0700 (PDT)
> I am documenting a family of APIs in the world of C and Visual Basic....
> Many of the arguments to the functions are optional, offering default
> values. Some are simple flags (true or false), some can take one of a short
> list of values, and some take an expression (such as a file name, or a
> formatting string).
> Now, I have a syntax summary appendix, which the reader who is acquainted
> enough with the API would use as a handy reminder about the signature of any
> function. BUT, the down side of a BatchArgs argument is that my summary
> appendix shows only that such functions USE a BatchArgs argument, but gives
> no clue about which of the (scores of) names are acceptable in it.
I'm not sure I *totally* understand what you mean, and I come from a
Delphi/Java background (more Java than Delphi of late), but if I was going to
use an API function, I'd definitely want to know what the signatures are for
it. It seems to me that you can use the standardized syntax to show the
variable-ness of the various elements (with the {} symbols), and could provide
a list of all of the various signatures supported. That way, your readers could
search through the elements in each signature, and find the one that contains
all of the elements that they want to specify, and use that one.
If I'm way off here, feel free to contact me off-list. It's been a few years
since I have worked with a product that had API documentation (and even that,
fellow listmember Martha Kolman actually owned the API doc), but I could
certainly tell you what *I* would want when I'm wearing my programmer hat.
__________________________________________________
Do You Yahoo!?
Yahoo! Health - Feel better, live better http://health.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
