Quote:
Originally Posted by kamelito
Amiga developer CD 2.1 too, I hope that Olsen he’s still working on improving developer material.
|
Yes, indeed. This is what I spent the past few months on, trying to finish the NDK 3.2R5. By accident, the focus of this NDK3.2 update shifted towards improving the dos.library documentation and the 'C' header files. The dos.library documentation has always been lacking, right from the start and while it improved over the decades, the "best" version in NDK 3.2R4 would still contain huge gaps which ought to have been filled a long time ago.
Unless something unexpected happens, you may be able to look forward to see a major rework of the dos.library AutoDocs.
The documentation has been reformatted to improve accessability. More bugs recently discovered (some of them are more than 30 years old) and fixed are now covered in the documentation. There is a completely new introduction to dos.library and its underpinnings, with a large section covering the limitations, unexpected constraints (e.g. stack size requirements, path length limitations and silent truncation) and even advice on what to watch out for, if you want to stay on dos.library's good side (if there is one; this is still part of cutting-edge research).
Every single AutoDoc entry for dos.library has been updated and the relevant data structures, e.g. used by Lock(), Open(), Examine(), Info(), are covered in context. The AutoDoc entries now feature new sections ("warnings" and "notes"), where needed, which describe what pitfalls lie ahead and which complex problems you might face. For example, NameFromLock() can produce path names which will be longer than Open(), Lock() or Rename() can handle. These warnings are repeated in the respective entries, rather than collected in one single section, so that you can look up the respective function and see what might be in store for you. The AutoDocs are supposed to be brief and to the point, but dos.library is arguably an exception. Next to graphics.library, it contains the most complex of the AmigaOS APIs, some of which are poisonously easy to get wrong ever so slightly (such as ExAll()).
The corresponding 'C' header files have been reformatted and updated in order to make them more accessible and provide more context. For example, the relationship between the DosPacket types and the dos.library functions is documented now.
These changes to the dos.library documentation spilled over into exec.library and expansion.library documentation changes, too.