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.
>I've looked at some documentation for .NET classes and it seems like they
>document the overloaded functions separately based on data type, i.e.
>Func(object), Func(char), Func(int).
My take on this is that it depends on the function and why it's overloaded.
For example, let's say you have a diameter() function that takes a single
numeric radius argument. That radius argument could be int, double, long,
etc. And in each case, the function returns the diameter as the same type
as its argument. In that case, it makes sense to group all the doc together,
since the common functionality is the same; just specify what types of
arguments it can take, and that the result will be the same type as the
argument. Example:
diameter(int)
diameter(double)
diameter(long)
Diameter takes a number value of a circle's radius, calculates the
circle's diameter, and returns the diameter value as the same type as
its argument.
Another situation would be if you had a foo() function which could
take arguments a, b, c, etc., where all arguments after a are optional. In
other words, the function is defined for foo(a), foo(a, b), foo(a, b, c).
In this case, again it makes sense to me to document it once, and explain
how the optional arguments affect the function after explaining the core
functionality of foo(a), the required argument. Example:
foo() <general comment>
foo(double a) : a is a required argument for all calls to foo. When only a
is given, foo doubles a and returns it.
foo(double a, boolean b) : When b is true, a's value is doubled,
truncated to 2 digits to the right of the decimal point precision, and
returned. When b is false, a's doubled value is not truncated before
its return.
foo(double a, boolean b, boolean c) : b affects the function as described
above. If c is true, the result display is colored red, if c is false,
the result display is colored blue.
On the other hand, if functionality is substantially different, it'd make
sense to me to break out separate descriptions of each parameter set within
an overall entry of the name of the function. For example:
foo() : <general comment>
foo(int) : doubles the value and returns it.
foo(object) : Extracts the value of object's number field, doubles the value,
sets the object's number field to the doubled value, and
returns the doubled value.
tyg tyg -at- Panix -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
