Agreed. The current inconsistant deprecation identification should be deprecated.
The problem extends far beyond the exec autodoc. Do a search of the words "deprecated" and "obsolete" in the autodocs and includes. There are many inconsistancies like in bevel_ic.doc the description of IA_APatsize mentions "a deprecated BEVEL_FillPattern" and yet BEVEL_FillPattern is not marked as deprecated. The dos autodoc (and maybe asl) comes closest to accurately identifying deprecated functions but is inconsistant in it's identification. Deprecated functions are identifyed with (--DEPRECATED v50--), [DEPRECATED v52.16], DEPRECATED FUNCTION, (DEPRECATED) and others. We need to have a consistant method of tagging deprecated functions like:
[DEPRECATED version - status] (replacement function or workaround) {comment}
Where:
version = version number when it became deprecated (e.g. v52.1)
status = One of several SDK-wide definitions (without the arrows) like:
>>>>>OBSOLETE = Continues to work but should be replaced with another function.
>>>>>REMOVED = No longer available - do not use.
>>>>>DANGEROUS = Does not produced defined results or causes program failure.
replacement function = The function that should be used instead.
comment = any important related facts
The same method should also be used in the includes; possibly included in comments. According to the GCC docs: functions, variables and types can be marked as deprecated and produce compiler warnings. Definitions would need to have the deprecated identification contained in a comment. In fact, DEPRECATED is defined in amiga_compiler.h so that GCC will issue warnings about deprecated functions etc. The only include file that takes advantage of that functionality is interfaces/dos.h! If you use a function like Execute() you will get a compiler warning. All the includes should have deprecated functions, variables and types marked this way to aid in identifying them in (for example) 68k code that is being ported to OS4. I think the extent of the deprecation needs to be explicit as in the "status" example above so that programs compiled for multiple systems can identify functions that may be dangerous when used with OS4.
Your exec.h comment about AllocEntry() is a good example of a deprecated function that should be flagged as DEPRECATED in the includes but isn't. Someone in the OS4 development hierarchy should be assigned the task of cleaning up the OS4 includes and eliminating the inconsistancies like the ones we're discussing.
EDIT: Additionally, it wouldn't be hard to write an SDK command that would scan the includes for deprecated functions, variables, types, definitions and then identify them in program sources if a consistant identification method like the one I suggested above were applied to the OS4 includes.