RE: Documenting overloaded functions

Subject: RE: Documenting overloaded functions
From: "Mark Baker" <mbaker -at- ca -dot- stilo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 24 Apr 2003 15:51:52 -0400


Rowena Hart wrote:

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



References:
Documenting overloaded functions: From: Rowena Hart

Previous by Author: RE: Reader responsibility
Next by Author: alternative to the word module
Previous by Thread: Re: Documenting overloaded functions
Next by Thread: RE: Documenting overloaded functions


What this post helpful? Share it with friends and colleagues:


Sponsored Ads