(summary) c++ api help: tips & resources
If I have to, I heard that you can extract infoyou have any
from header files. Do you know what the file extension for those are? Do
sample header file to show me what I should look for? A fake
example would
be fine.
We writers at my company get most of our information for the reference
material from looking at the header files for our products. We seldom get
much if anything written from the developers themselves! Fortunately, we are
able to use the ActiveX version of our controls in Visual Basic, so that
gives us a head start on understanding the C++ use of the controls.
In any event, the header files are generally text files. Ours for working in
C++ usually have the extension .H or .CPP. You should be able to read them
in a text editor. You shouldn't need Visual Studio to view them, but if you
double-click one and have VS installed, it will open Visual Studio. You're
better off just viewing it in a text editor, I think.
As for a sample header file, I'm not sure ours would be similar to yours,
but I'm attaching two, along with our online help file for that product
(Input Pro). Perhaps it will help you with your work. I hope so.
I have understanding from Java code how to tell what classes, methods,
parameters, return types look like but am not sure how different
this may be
for c++. Are header files in text format or do I need Visual
Studio to view
these?
I think your work in Java will help you get started in C++ pretty quickly.
Our controls are not really broken up into objects as some are, so our
header files might not be too similar to what you see at your company.
However, from your experience in Java, I think you'll be able to read your
C++ header files pretty easily and figure out classes, methods, parameters,
and return types.
Once we get pretty familiar with a product, we writers find we can usually
tell from the method name the intent of the programmer, and figure out most,
if not all, of the parameters and what they do. We can usually extrapolate
from there to figure out how to use it along with other methods to
accomplish some programming task.
By the time you take what the programmer gives you, the header file, and
some time and thought, you will probably be able to construct a pretty solid
reference for your API. Some review by the programmer, some more work by
you, and you will probably be in pretty good shape for the reference
material.
When you have time or interest, you might want to read two excellent
articles by Susan Gallagher about API writing. You can read them on her web
site at http://pw1.netcom.com/~gscale/susanwg/cmindware/article1.htm (scroll
to the bottom to see the two on documenting APIs). The one titled "Yesterday
API was just another acronym" would probably be VERY helpful for you right
now, actually. I highly recommend it.
If you keep on in this line of tech writing, you might want to consider
taking a workshop on it, such as the one recently offered by Gordon and
Gordon (http://www.gordonandgordon.com/apisandsdks.html) in Montreal. Of
course, programming courses would be helpful, too. I've been doing API docs
for 6+ years, though, and have been able to avoid programming courses so
far. ; ) I'm sure they'd be useful, though.
I hope this helps you some, Carol. I know API writing can be tough
sometimes, and very confusing, especially when you're just starting to work
with a product. I hope your developer is a helpful sort, and this will go
smoothly for you.
Best wishes,
Lydia : )
--------------------
Lydia Wong
Technical Writer
FarPoint Technologies, Inc.
www.fpoint.com <http://www.fpoint.com>
---
If you understand Java, you should have a reasonably good basic
understanding of C++, since Java is based on C++.
Header files normally have a ".h" extension. That is the convention in C,
which C++ is based upon. You may see extensions like ".hxx" or something.
Header files are part of programming libraries. They refer the compiler to
the library containing the definitions and functions used in the progrram.
For instance, the line "#include <iostream>" tells the compiler to look in
the iostream file in the standard C++ library to find out what "cout <<
endl" means. It is similar in function to the "import" keyword in Java.
Libraries are simply a collection of program functions, variables, etc.
bundled for reuse in other programs.
All source files in a C/C++/Java program are text files that can be read in
a simple text editor such as emacs, vi, or notepad. So go to the source and
have a ball ;)
HTH, if you have other questions I can help with, let me know.
John Gilger
Senioir Technical Writer
Acres Gaming, Inc.
702.914.5585
<JGilger -at- acresgaming -dot- com>
---
For comparative purposes, you might get your hands on a beginners Java book.
Most of them begin to explain Java in terms of how it differs from C++.
<Richard -dot- Smith -at- windriver -dot- com>
---
hi, i have some notes on how to document c++ from a class my friend took.
you might find these useful, in addition to all the automated tool info
the techwr-l people have posted.
http://www.petting-zoo.net/~jool/techwriting/documentingC.html
Also, i have an outline for developing an API guide
http://www.petting-zoo.net/~jool/techwriting/api_outline.html
Good luck!
-jool
julie brodeur <jool -at- petting-zoo -dot- net>
---
One of the main differences between Java and C++ is
the logical structure of the code. Java stores all
the information about the class in a single file and
when it generates bytecode, all of the information
about the code disappears into neverneverland. That's
why javadocs comes with, so you can see what's inside.
C++, OTOH, stores information about the class in the
header file (.h) and the implementation (mostly) for the
class goes in the source file (.c, .cpp, etc. depending
on the compiler). When you compile c++ code, the
implementation goes to neverneverland; the header file
remains in plain text. <TIC> That's why *real* c++
programmers don't need no stinkin' reference docs!</TIC>
;-) They can always browse the header files to see
what the library includes.
What you see in the header file is the definition for
the class. It:
* uses include statements to call in functionality
from other classes
* declares the name of the class
* lists one or more parent classes
* declares the signatures for all the methods
in the class (some methods may be implemented
in-line, even though this circumvents encapsulation)
* declares the data members for the class
While Java, with a few exceptions, follows a one-class/
one-file model, I've seen upwards of 200 classes declared
in a single header file.
The syntax and the method signatures are very similar, so
you shouldn't have too much trouble there.
One difference that you'll find is that Java uses access
modifiers in front of every element while c++ uses access
modifiers as section identifiers.
Additionally, you'll need to pay attention to the differences
in polymorphism. In java, polymorphism is the default and you
need to use the _final_ keyword to turn it off. In c++, you
need to specifically turn polymorphism _on_ using the keyword
_virtual_.
The java _interface_ equates to the c++ abstract base class
in that it is impossible to instantiate an object in either
case. Declaring an abstract base class in c++ is simply a
matter of setting a virtual method equal to zero within a
class declaration. So it's certainly not as obvious as in
Java, where you declare an interface rather than a class.
Be sure that you point out abstract base classes and the
methods that are set equal to zero (in c++, those are called
_pure_virtual_methods_).
One of the nice things about Java is that it has automatic
garbage collection and it doesn't have pointers. Pointers
are a very powerful, *PIA* feature of c++ where you point
to where the data is stored instead of calling the data
by name (sort-of). Pretty much all you need to know from
a documentation POV is that whenever you see either an
asterisk or "_ptr" in the return value, you need to tell
the audience whether it's their responsibility to release
the memory when they're done with it. Not releasing the
memory causes memory leaks causes programs to crash, so
that's important.
HTH! Feel free to email me with any other questions, but
I suggest we take more specific questions offline before
everybody else's eyes glaze over. <giggle!>
-Sue Gallagher
susanwg -at- ix -dot- netcom -dot- com
---
Hi Carol,
header files are .h files. usually they have the same name as the .c or .cpp files so you can tell which header file goes with which. usually header files contain a list of constants (which you probably don't need to document), and a list of functions (which is like methods in java). if the developers are good with documentation (standard practice), they should write more "elegible" codes so that without looking at the body of the code but just the header file, you can tell what's the input and output. a good example for a header file:
int ConvertFromString(char *strNumber);
so you can tell that the return type is a number (int) and input is expected to be a string (character array in c).
if yyou don't know which header file (.h) to look for, look at the first couple of lines in a .c or .cpp file for:
#include "header.h"
#include <myheader.h>
i hope this helps.
~Julia (C++ programmer)
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline April 27. http://www.pdfconference.com.
---
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:
help: tips from c++ api writers
Next by Author:
(summary) c++ api help: extraction tools
Previous by Thread:
Re: FrameMaker
Next by Thread:
(summary) c++ api help: extraction tools
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads