Hyperion Entertainment Message Boards

The highlight of the depreciation state of a given function is not always very clear and sometimes hard to find in exec's autodoc.
For example:

• AllocEntry (the way I prefer): clearly noted as deprecated in the first line of its associated documentation. There a big

  (-DEPRECATED-)

  at the end of the first line and just below the new function to use instead is explicitly given.
• AllocTrap (another way of doing it, worse IMHO): clearly noted as 'Obsolete' in the first line of its associated documentation. There is a

  (Obsolete)

  at the end of the first line but no mention if there is a replacement function or not, one has to read the full documentation to eventually understand this function has no purpose on our new processor architecture.
• AllocVec (the worst IMHO): no mention on the first line. There is just a sentence in the NOTE section saying this function is obsolete and the replacement is AllocVecTagList; fortunaltely this is the only sentence. But for instance the CachePreDMA contains one sentence in the middle of the NOTE section saying that it's obsolete together with CachePostDMA and should be replaced by StartDMA/EndDMA this isn't obvious the function is obsolete until you read this very single line in the NOTE section, worse CachePostDMA doesn't even mention it's obsolete and should be replaced by EndDMA.

I thing that to clarify the documentation a single term should be adopted (deprecated is the best IMHO) and when a replacement exists there must be a convention on how to mention it. The most convenient way is AllocEntry IMHO which gives all the information on its first line and in a compact form (some details can be added in the NOTE section of course).

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.