Nit pick -- where to stick the * in a C/C++ definition

Subject: Nit pick -- where to stick the * in a C/C++ definition
From: "Haas, Guy" <ghaas -at- selectica -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 1 Mar 2001 13:13:35 -0800

I am documenting an API in C++. I need to decide on a
standard representation for pointer definitions.
C and C++ themselves don't care whether I say:

int * foo //centered
int* foo //closed left
or int *foo //closed right

I had decided to go with the "closed left" form,
and was chatting with a developer. He agreed that
it was typical, but reminded me that if one opts
to define multiple pointers on one line, the asterisk
must precede each name. If one writes

int* foo, bar

one has defined a pointer-to-integer named foo and
an integer named bar. To get both to be pointers,
one must put an asterisk before each -- in which
case, it looks better to use "closed right" form:

int *foo, *bar

Now, my document is going to have one definition per line
in the explanations. There is a chance that examples
would include compound definitions, solely in the interest
of saving vertical space.

What is the collective wisdom on positioning the asterisk
in API documentation?

--Guy K. Haas gkhaas -at- usa -dot- net
Software Exegete in Silicon Valley

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by ForeFront, Inc., maker of ForeHelp Help authoring tools
for print, WinHelp, HTML Help, JavaHelp, and cross-platform InterHelp
See www.forehelp.com for more information and free evaluation downloads

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


Previous by Author: RE: European tech writing conferences
Next by Author: FW: RE: Resources for Service Level Agreements
Previous by Thread: RE: Bad Service from nSight Training
Next by Thread: Re: Nit pick -- where to stick the * in a C/C++ definition


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


Sponsored Ads