========
OVERVIEW
========


scdep pragma markup is used to provide details inside of .c or .h files, so
that .scc or .sch files can be auto-generated from the markup.


if preprocessing is needed, i.e. the dependencies themselves depend on C
preprocessor definitions, details about the defines can also be provided using
the scdep pragma markup, so that .scb or .scg files can be auto-generated.


(.scb or .scb files use the same format as .scc or .sch files, except .scb or
.scg files need preprocessed first, to become .scc or .sch files).



======
SYNTAX
======

the scdep pragma syntax is:

	#pragma scdep_includes_system_header "<stdio.h>"
	#pragma scdep_includes_user_header "stdio.h"
	#pragma scdep_defines_datum "FOO"
	#pragma scdep_defines_function "FOO"
	#pragma scdep_uses_datum "FOO"
	#pragma scdep_uses_function "FOO"
	#pragma scdep_declares_datum "FOO"
	#pragma scdep_declares_define "FOO"
	#pragma scdep_declares_enum "FOO"
	#pragma scdep_declares_function "FOO"
	#pragma scdep_declares_macro "FOO"
	#pragma scdep_declares_struct "FOO"
	#pragma scdep_declares_typedef "FOO"
	#pragma scdep_declares_union "FOO"
	#pragma scdep_requires_datum "FOO"
	#pragma scdep_requires_define "FOO"
	#pragma scdep_requires_enum "FOO"
	#pragma scdep_requires_function "FOO"
	#pragma scdep_requires_macro "FOO"
	#pragma scdep_requires_struct "FOO"
	#pragma scdep_requires_typedef "FOO"
	#pragma scdep_requires_union "FOO"


i.e. the item type, followed by the value, with the value inside double quotes.


For simplicity of parsing, each pragma statement needs to only be on a single
line.


Escaped double quotes are allowed, i.e.

	\"

can be used inside the double-quoted value for an embedded double quote.


Optionally, if the quoted value starts with $, e.g. "$FOO", this indicates that
the value needs to be preprocessed, even if there are no further conditionals
that require preprocessing.


An example would be for marking up code such as:


	#define FOO_FUNCTION my_foo

	extern void FOO_FUNCTION(void);


which we would describe with:


	#pragma scdep_declares_function "$FOO_FUNCTION"


for this example, we want to indicate that a function is being declared, but
the name of the function being declared comes from a preprocessor definition,
and in order to capture this properly, our description should use the same
define, rather than e.g. hard-coding the function name my_foo.



============
CONDITIONALS
============

After the value portion of a pragma, one or more of:

	"def::FOO::"
	"ndef::FOO::"
	"eq::FOO::3::"
	"neq::FOO::3::"
	"gt::FOO::3::"
	"ge::FOO::3::"
	"lt::FOO::3::"
	"le::FOO::3::"

may be used to indicate conditional preprocessor tests.


These examples translate to:

	#ifdef FOO
	#ifndef FOO
	#if (FOO == 3)
	#if (FOO != 3)
	#if (FOO > 3)
	#if (FOO >= 3)
	#if (FOO < 3)
	#if (FOO <= 3)


As an example, a source .c file or .h file containing:

	#ifndef NO_FOO
	#ifdef DEC_FOO
	extern void foo(void);
	#endif /* #ifdef DEC_FOO */
	#endif /* #ifndef NO_FOO */


we would describe with:


	#pragma scdep_declares_function "foo" "ndef::NO_FOO::" "def::DEC_FOO::"


and the auto-generated .scb or .scg file would either use the exact code below,
or something very similar to the code:


	declares_functions

	#ifndef NO_FOO
	#ifdef DEC_FOO
		foo
	#endif /* #ifdef DEC_FOO */
	#endif /* #ifndef NO_FOO */

	;