----------------------------------------------------------------------------
Autodoc style guide - June 1990
----------------------------------------------------------------------------

Autodocs are part of each source module.

Autodoc looks at the start of each line, and considers a match of the
pattern "/****** " or "******* " as the start of an autodoc (* or /, 6
asterisks, then a space).  An autodoc ends with at least three asterisks at 
the start of a line ("***").  If the start string is "/****i* " the autodoc is
"internal", and will be extracted only if the "internal" flag of autodoc is
enabled (this does not work yet).

Please look at your autodoc output to see if it has problems before
releasing.


Here is a sample "correct" autodoc:


/****** financial.library/StealMoney ******************************************
* 
*   NAME	
* 	StealMoney -- Steal money from the Federal Reserve Bank. (V77)
* 
*   SYNOPSIS
*	error = StealMoney( userName,amount,destAccount,falseTrail )
*	D0,Z                D0       D1.W    A0         [A1]
*
*	BYTE StealMoney
*	     ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
*
*   FUNCTION
*	Transfer money from the Federal Reserve Bank into the specified
*	interest-earning checking account.  No records of the transaction
*	will be retained.
* 
*   INPUTS
* 	userName      - name to make the transaction under.  Popular favorites
*	                include "Ronald Reagan" and "Mohamar Quadaffi".
*	amount        - Number of dollars to transfer (in thousands).
*	destAccount   - A filled-in AccountSpec structure detailing the
*	                destination account (see financial/accounts.h).
*			If NULL, a second Great Depression will be triggered.
*	falseTrail    - If the DA_FALSETRAIL bit is set in the destAccount,
*			a falseTrail structure must be provided.
*	
*   RESULT
* 	error - zero for success, else an error code is returned (see
*	        financial/errors.h).  The Z condition code is guaranteed.
* 
*   EXAMPLE
*	Federal regulations prohibit a demonstration of this function. 
*
*   NOTES
*	Do not run on Tuesdays!
*
*   BUGS
* 	Before V88, this function would occasionally print the address and
*	home phone number of the caller on local police 976 terminals.
*	We are confident that this problem has been resolved.
* 
*   SEE ALSO
* 	CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
*	financial/misc.h
* 
******************************************************************************
*
* 	Private notes:
*		A4=stringbean
*		A3=dogbreath
*	Must preserve A1 for taxshelter.library
*/

A "blank" version of this autodoc is provided at the end of this file.
There are three spaces from the * to the start of each HEADING.  There
is one tab after the * before the start of the body text.  No other tabs
are used.


------------------ general style notes -----------------------------------

It is critical that changes be noted in a sane manner.

When referring to a function, the standard format is FunctionName().


Capitalization should be correct.  Here are some guidelines:

	1> The words Amiga, Exec, Workbench, Autoconfig, AmigaDOS, Kickstart,
	   Commodore, Commodore-Amiga, etc.  all are trademarks, and *must*
	   be capitalized.

	2> Names of "things" are as defined.  For example, "OpenWindow()",
	   and "a Window structure".  "fiddles with your window" does not
	   refer to the structure, and should not be capitalized.


Lines terminate at column 77, so the autodocs are readable from within
an Amiga CLI window.


------------------ heading-by-heading description ------------------------


---------------------------------
******* modulename.type/FunctionName *************************************
---------------------------------

	GOOD
		exec.library/AddTail
		math<various>.library/Function
		audio.device/CD_ASKDEFAULTKEYMAP
	
	BAD
		Library/Translator/Routine
		Routine
		Resources/Misc/Routine
		audio.device/AskKeyMap

Before the / is the module name (as the caller sees it).  After the / is the
function or command name (as the caller sees it).  For devices this is the all
caps command placed into IO_COMMAND.  The special function name
"--background--" may be used for background information common to many
functions.


/*
******* zip.zoop/Zum **************

Is an alternate form.


---------------------------------
*   NAME	
* 	StealMoney -- Steal money from the Federal Reserve Bank. (V77)
---------------------------------
Put YourFunctionName, " -- ", then a ONE LINE description of what it does.
Real sentences with periods are preferred.


---------------------------------
SYNOPSIS
---------------------------------

The SYNOPSIS has three parts.  The C calling convention, the
assembly registers, and (new) the function prototype.

Do NOT indicate that the library base goes in A6, unless there is
something special about your module.  If parts of a register are
ignored, note that next to the register number.  The standard form
is the register number followed by the number of bits (D0:16).  *Only
specify this if the upper bits are, and always will be, ignored*.

An ANSI standard prototype is a new addition to our specification.
This must be a ready-to-compile indication of the function's types.
Do *not* use the base types, use the "types.h" file.  This line must compile!


Base type          Use these typedefs            notes
----------------------------------------------------------------------------
--untyped pointer--	void *	   [  void *AllocMem( ULONG,ULONG );       ]
--no parameter/return--	void	   [  void RemakeDisplay(void);            ]
--function pointer--	???	   [  (unresolved issue)                   ]

unsigned char *		STRPTR	   [ "char *" is -not- acceptable!!        ]
short			WORD
unsigned short		UWORD
unsigned short *	UWORD *    [  word aligned pointer]
unsigned long *		ULONG *    [  word aligned pointer to ULONG object ]
			BPTR       [  Our old friend			   ]


There is one line where you name the parameters and return values,
another where you do the registers, and a third with the prototype
that replaces the UNIX style type declarations that some few modules used
(intuition mostly).  So, you can still refer to parameters and return
values by name in the description.

old-style:
	RealPos = RemoveGadget( Window, Gadgets, Pos )
	  D0			  A0	  A1	  D0
	
	UWORD	RealPos;
	struct Window	*Window;
	struct Gadget	*Gadgets;
	UWORD		POS;

becomes:
	RealPos = RemoveGadget( Window, Gadgets, Pos )
	  D0			  A0	  A1	  D0
	UWORD RemoveGadget( struct Window *, struct Gadgets *, UWORD );


If any of these lines are too long, exert your individuality and word-wrap
it! 


---------------------------------
FUNCTION
---------------------------------
 
	!describe WHAT your function does in generally accepted English,
	!keep jargon to a minimum, but don't sacrifice clarity and accuracy.
	!You may even take the radical step of using a spelling checker. Nah.

---------------------------------
INPUTS
---------------------------------
Describe the range and domain of each input parameter.  Use the same
name token used in the first SYNOPSIS line (so the user can match inputs
to the descriptions).  The preferred follower is "-". (See example)
Don't forget to note the actions taken for NULL pointers!.

The suggestion has been made to standardize on:

	TheToken - If the description is long, then indent the second line
	    by 4 spaces.  Many modules currently use whatever number of spaces
	    looks good.


---------------------------------
RESULT
---------------------------------
Describe the range and domain of each output.
Describe which abnormal conditions produce each error output.


---------------------------------
EXAMPLE
---------------------------------
An optional *short* example of how your function is called.  This must BE
TESTED.  Write, test, then remove lines if needed to shorten the example.
Use "..." to indicate removed sections.  Do not edit the example after
creation (unless you retest).

| Sadly some compilers do not allow nested C comments.  Instead we will
| reverse the \, and have autodoc magically fix things up.

	\* write this in your autodoc *\
	/* and autodoc will convert to the standard form */

| Be sure to search old source code created prior to this new definition!

---------------------------------
NOTES
---------------------------------
	Helpful hints, warnings, tricks, traps, etc. (optional)


---------------------------------
BUGS
---------------------------------
	!if there are any, describe the bug, and how it can be avoided.
	List versions, workarounds, etc.

---------------------------------
SEE ALSO
---------------------------------
	If there are other functions which help describe the data structures,
	or are otherwise related to this function, place their names here.
	Note include files, where appropriate (it is acceptable to list
	just the ".h" file, an assume the assembly user will find the ".i".)

	Functions in THIS module are simply listed, with () to indicate they
	are a function.  Functions from OTHER modules are preceded by the
	module name.  (See the StealMoney() autodoc for examples).


NOTE: See autodoc.sample for other templates


/****** / ******************************************
*
*   NAME	
*
*   SYNOPSIS
*
*   FUNCTION
*
*   INPUTS
*
*   RESULT
*
*   EXAMPLE
*
*   NOTES
*
*   BUGS
*
*   SEE ALSO
*
******************************************************************************
*
*/

