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.
> Is this the "standard" way to document overloaded
> functions? It seems very repetitive/verbose to me. Is
> there a simpler way to document overloaded functions
> that would still allow programmers to quickly access
> the info they need?
We have this situation exactly in our documentation for OmniMark. The way I
approach it is this: if the function is overloaded it is because all cases
of the function perform conceptually the same operation, just on different
data types. The reason that the function is overloaded is that it is the
same operation, and it is the operation that is documented, not the
implementation of the functions that perform that operation. Therefore, the
operation is documented once.
If this approach does not work for a particular case, that is, if the
operation being performed by the different functions is in fact
significantly different, then you have to ask why the functions that perform
these diverse operations were overloaded in the first place.
The motivation for overloading functions is that two operations which are
conceptually identical should have the same name. The converse is that that
two operations that are conceptually different may happen to be described by
the same word in English (good old ambiguity). When this occurs, the
functions should not be overloaded. Instead, different names should be
chosen to disambiguate the different concepts.
---
Mark Baker
Senior Technical Writer
Stilo Corporation
1900 City Park Drive, Suite 504 , Ottawa, Ontario, Canada, K1J 1A3
Phone: 613-745-4242, Fax: 613-745-5560
Email mbaker -at- ca -dot- stilo -dot- com
Web: http://www.stilo.com
This message, including any attachments, is for the sole use of the
intended recipient and may contain confidential and privileged
information. Any unauthorized review, use, disclosure, copying, or
distribution is strictly prohibited. If you are not the intended
recipient please contact the sender by reply email and destroy
all copies of the original message and any attachments.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Last chance to order RoboHelp X3 and receive a $100 mail-in rebate,
PLUS free RoboScreenCapture and WebHelp Merge Module. Offer expires
4/30/03! Order here: http://www.ehelp.com/techwr-l
Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday 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.
