Copyright (c) Hyperion Entertainment and contributors.

Autodoc Style Guide

From AmigaOS Documentation Wiki
Jump to navigation Jump to search

Amiga Autodocs

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

Module/Function Name

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

*   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

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

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

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

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

EXAMPLE

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

NOTES

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

BUGS

BUGS

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

SEE ALSO

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

Example

NOTE: See autodoc.sample for other templates 

/****** / ******************************************
*
*   NAME	
*
*   SYNOPSIS
*
*   FUNCTION
*
*   INPUTS
*
*   RESULT
*
*   EXAMPLE
*
*   NOTES
*
*   BUGS
*
*   SEE ALSO
*
******************************************************************************
*
*/
Retrieved from "http://wiki.amigaos.net/w/index.php?title=Autodoc_Style_Guide&oldid=6046"