----------------------------------------------------------------------------
The official autodoc style guide, version 1.2  (FINAL).
Contains the Rob Peck style notes.
----------------------------------------------------------------------------
Tue May  2 17:17:22 EDT 1989 -Bryce Nesbitt

HISTORY (from Rob Peck)

As I tried to put together the V1.1 ROM Kernel manual, I encountered
many instances of style incompatibility between the various forms
of autodoc.  For the 1.2 release, since people for the most part
are handling much of their source code anyway, it should not be
difficult to modify the system-source to remove these problems.

HISTORY (from Bryce :-)

As I tried to put together the V1.3 ROM Kernel manual, I encountered
many instances of style incompatibility between the various forms
of autodoc.  For the 1.4 release, since people for the most part
are handling much of their source code anyway, it should not be
difficult to modify the system-source to remove these problems.

----------------------------------------------------------------------------


Autodocs are part of each source module.  Typing "make doc" will
extract the autodocs from each source file, and build the .doc file.
Autodoc can also be invoked manually:

	cat *.c *.asm >/tmp/1
	autodoc /tmp/1 >module.doc

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=fishbreath
*	Must preserve A1 for deathwish.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.  Developers
will want to write for old-ROM compatibility; we must CLEARLY note V36 changes.


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


Capitalization is an unstable mess at the moment.  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.

	   We can fight over "serial.device" vs. "the Serial device".


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.

| If the function was added anytime after V33, this will be noted in at least
| two places.  First is in parenthesis at the end of the one-liner description
| (see above).  Second is in the .fd file for the module.

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

The SYSNOPSIS 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 our compiler does 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.

	We have standardized on the release number for describing bugs.
	Say "fixed in V36" not "fixed in V1.4".

| !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
| !!!!!!!!!!!!!! DO NOT FORGET TO MENTION KNOWN BUGS.  THERE ARE FEW BETTER
| WAY TO PISS OFF A DEVELOPER THAN BY "HIDING" KNOWN BUGS !!!!!!!!!!!!!!!!!
| !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

	"BUGS" IS OPTIONAL ONLY IF YOUR FUNCTION IS AND WAS BUG FREE!


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


*******************************************************************************
Unresolved issues:

     1> For devices, how do we handle the "standard" functions?
	Does each device need an entry for OpenDevice/CloseDevice/
	CMD_READ, etc?  How do we note, for example, that timer.device does
	not support CMD_READ?  Currently most docs list every supported
	standard command, device specific command, or function 
	with a separate autodoc page.
	   


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

