Autodoc Style Guide - Revision history

Steven Solie: /* Amiga Autodocs */

2015-07-06T22:15:33Z

Amiga Autodocs

← Older revision		Revision as of 22:15, 6 July 2015
Line 3:		Line 3:
	Autodocs are part of each source module.		Autodocs are part of each source module.

	Autodoc looks at the start of each line, and considers a match of the		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 ("***").
	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		If the start string is "/***i " the autodoc is "internal" and will be extracted only if the "internal" flag of autodoc is enabled (V53.1).

	"~~internal~~", and will be extracted only if the "~~internal~~" flag of autodoc is		If the start string is "/***o " the autodoc is "obsolete" and will be extracted only if the "obsolete" flag of autodoc is enabled (V53.2).
	enabled (this does not work yet).

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

	Here is a sample "correct" autodoc:		Here is a sample "correct" autodoc:

	<pre>		<pre>
	/**** financial.library/StealMoney ****************************************		/**** financial.library/StealMoney ****************************************
Line 19:		Line 18:
	* NAME		* NAME
	* StealMoney -- Steal money from the Federal Reserve Bank. (V77)		* StealMoney -- Steal money from the Federal Reserve Bank. (V77)
	*
⚫	* SYNOPSIS
⚫	* error = StealMoney( userName,amount,~~destAccount,falseTrail )~~
	* D0,Z D0 D1.W A0 [A1]
	*		*
		⚫	* SYNOPSIS
	* BYTE StealMoney
		⚫	* int8 error = StealMoney(CONST_STRPTR userName, uint16 amount,
	* ( STRPTR,UWORD,struct AccountSpec ,struct falseTrail );
			* struct AccountSpec *destAccount,
			* struct falseTrail *falseTrail);
	*		*
	* FUNCTION		* FUNCTION
	* Transfer money from the Federal Reserve Bank into the specified		* Transfer money from the Federal Reserve Bank into the specified
	* interest-earning checking account. No records of the transaction		* interest-earning checking account. No records of the transaction
	* will be retained.		* will be retained.
	*		*
Line 70:		Line 67:
	</pre>		</pre>

	A "blank" version of this autodoc is provided at the end of this ~~file~~.		A "blank" version of this autodoc is provided at the end of this article. There are three spaces from the * to the start of each HEADING. There
	~~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.
	is one tab after the * before the start of the body text. No other tabs
	are used.

	= General Style Notes =		= General Style Notes =

Steven Solie: /* SYNOPSIS */

2013-06-13T18:45:17Z

SYNOPSIS

← Older revision		Revision as of 18:45, 13 June 2013
Line 143:		Line 143:
	Do not use the base types, use the "types.h" file. This line must compile!		Do not use the base types, use the "types.h" file. This line must compile!

			{\| class="wikitable"
	<pre>
	Base type Use these typedefs ~~notes~~		! Base type !! Use these typedefs !! Notes
			\|-
	----------------------------------------------------------------------------
	--untyped pointer-- void * [ void *AllocMem( ~~ULONG~~,~~ULONG~~ ); ]		\| --untyped pointer-- \|\| void * \|\| void *AllocMem( uint32, uint32 );
			\|-
	--no parameter/return-- ~~void~~ [ void RemakeDisplay(void); ]		\| --no parameter/return-- \|\| void \|\| void RemakeDisplay(void);
⚫	--function pointer-- ??? [ (unresolved issue) ]
			\|-

		⚫	\| --function pointer-- \|\| ??? \|\| (unresolved issue)
⚫	unsigned char * ~~STRPTR~~ [ "char *" is -not- acceptable!! ]
			\|-
	short WORD
		⚫	\| unsigned char * \|\| STRPTR \|\| "char *" is -not- acceptable!!
⚫	unsigned short ~~UWORD~~
			\|-
⚫	unsigned short * ~~UWORD~~ * [ word aligned pointer]
			\| short \|\| int16
⚫	unsigned long * ~~ULONG~~ * [ word aligned pointer to ~~ULONG~~ object ]
			\|-
⚫	BPTR [ Our old friend ]
		⚫	\| unsigned short \|\| uint16
	</pre>
			\|-
		⚫	\| unsigned short * \|\| uint16 * \|\| word aligned pointer
			\|-
		⚫	\| unsigned long * \|\| uint32 * \|\| word aligned pointer to uint32 object
			\|-
		⚫	\| BPTR \|\| Our old friend
			\|}

	There is one line where you name the parameters and return values,		There is one line where you name the parameters and return values,
Line 169:		Line 176:
	D0 A0 A1 D0		D0 A0 A1 D0

	~~UWORD~~ RealPos;		uint16 RealPos;
	struct Window *Window;		struct Window *Window;
	struct Gadget *Gadgets;		struct Gadget *Gadgets;
	~~UWORD~~ POS;		uint16 POS;
	</pre>		</pre>

Line 179:		Line 186:
	RealPos = RemoveGadget( Window, Gadgets, Pos )		RealPos = RemoveGadget( Window, Gadgets, Pos )
	D0 A0 A1 D0		D0 A0 A1 D0
	~~UWORD~~ RemoveGadget( struct Window , struct Gadgets , ~~UWORD~~ );		uint16 RemoveGadget( struct Window , struct Gadgets , uint16 );
	</pre>		</pre>

Steven Solie: /* SEE ALSO */

2013-06-13T14:40:19Z

Steven Solie: /* BUGS */

2013-06-13T14:39:56Z

BUGS

← Older revision		Revision as of 14:39, 13 June 2013
Line 250:		Line 250:
	== BUGS ==		== BUGS ==

			<pre>
	---------------------------------
	BUGS		BUGS
			</pre>
	---------------------------------

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

	== SEE ALSO ==		== SEE ALSO ==

Steven Solie: /* NOTES */

2013-06-13T14:39:33Z

NOTES

← Older revision		Revision as of 14:39, 13 June 2013
Line 242:		Line 242:
	== NOTES ==		== NOTES ==

			<pre>
	---------------------------------
	NOTES		NOTES
			</pre>
	---------------------------------

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

	== BUGS ==		== BUGS ==

Steven Solie: /* EXAMPLE */

2013-06-13T14:39:17Z

EXAMPLE

← Older revision		Revision as of 14:39, 13 June 2013
Line 225:		Line 225:
	== EXAMPLE ==		== EXAMPLE ==

			<pre>
	---------------------------------
	EXAMPLE		EXAMPLE
			</pre>
	---------------------------------

	An optional short example of how your function is called. This must BE		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.		TESTED. Write, test, then remove lines if needed to shorten the example.
Line 233:		Line 234:
	creation (unless you retest).		creation (unless you retest).

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

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

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

	== NOTES ==		== NOTES ==

Steven Solie: /* RESULT */

2013-06-13T14:38:24Z

RESULT

← Older revision		Revision as of 14:38, 13 June 2013
Line 216:		Line 216:
	== RESULT ==		== RESULT ==

			<pre>
	---------------------------------
	RESULT		RESULT
			</pre>
	---------------------------------

	Describe the range and domain of each output.
	Describe ~~which~~ ~~abnormal~~ ~~conditions~~ ~~produce~~ ~~each~~ ~~error~~ output.		* Describe the range and domain of each output.
			* Describe which abnormal conditions produce each error output.

	== EXAMPLE ==		== EXAMPLE ==

Steven Solie: /* INPUTS */

2013-06-13T14:38:05Z

INPUTS

← Older revision		Revision as of 14:38, 13 June 2013
Line 197:		Line 197:
	== INPUTS ==		== INPUTS ==

			<pre>
	---------------------------------
	INPUTS		INPUTS
			</pre>
	---------------------------------

	Describe the range and domain of each input parameter. Use the same		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		name token used in the first SYNOPSIS line (so the user can match inputs
Line 207:		Line 208:
	The suggestion has been made to standardize on:		The suggestion has been made to standardize on:

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

	== RESULT ==		== RESULT ==

Steven Solie: /* FUNCTION */

2013-06-13T14:37:42Z

FUNCTION

← Older revision		Revision as of 14:37, 13 June 2013
Line 187:		Line 187:
	== FUNCTION ==		== FUNCTION ==

			<pre>
	---------------------------------
	FUNCTION		FUNCTION
			</pre>
	---------------------------------

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

	== INPUTS ==		== INPUTS ==

Steven Solie: /* SYNOPSIS */

2013-06-13T14:37:00Z

SYNOPSIS

← Older revision		Revision as of 14:37, 13 June 2013
Line 127:		Line 127:
	== SYNOPSIS ==		== SYNOPSIS ==

			<pre>
	---------------------------------
	SYNOPSIS		SYNOPSIS
			</pre>
	---------------------------------

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

	Do NOT indicate that the library base goes in A6, unless there is		Do NOT indicate that the library base goes in A6, unless there is
Line 144:		Line 143:
	Do not use the base types, use the "types.h" file. This line must compile!		Do not use the base types, use the "types.h" file. This line must compile!

			<pre>

	Base type Use these typedefs notes		Base type Use these typedefs notes
	----------------------------------------------------------------------------		----------------------------------------------------------------------------
Line 157:		Line 156:
	unsigned long * ULONG * [ word aligned pointer to ULONG object ]		unsigned long * ULONG * [ word aligned pointer to ULONG object ]
	BPTR [ Our old friend ]		BPTR [ Our old friend ]
			</pre>


	There is one line where you name the parameters and return values,		There is one line where you name the parameters and return values,
Line 166:		Line 165:

	old-style:		old-style:
			<pre>
	RealPos = RemoveGadget( Window, Gadgets, Pos )		RealPos = RemoveGadget( Window, Gadgets, Pos )
	D0 A0 A1 D0		D0 A0 A1 D0
Line 173:		Line 173:
	struct Gadget *Gadgets;		struct Gadget *Gadgets;
	UWORD POS;		UWORD POS;
			</pre>

	becomes:		becomes:
			<pre>
	RealPos = RemoveGadget( Window, Gadgets, Pos )		RealPos = RemoveGadget( Window, Gadgets, Pos )
	D0 A0 A1 D0		D0 A0 A1 D0
	UWORD RemoveGadget( struct Window , struct Gadgets , UWORD );		UWORD RemoveGadget( struct Window , struct Gadgets , UWORD );
			</pre>


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

	== FUNCTION ==		== FUNCTION ==

@@ Line 259: / Line 259: @@
 == SEE ALSO ==
 SEE ALSO
 = Example =