Cycling74/max-sdk

doc missing for class_new() style APIs

diablodale opened this issue · 2 comments

diablodale commented

The SDK doc is missing documentation for the class_new() style APIs. Instead, the SDK doc continues to have only the old deprecated setup() style APIs.

Two things are needed:

  1. end usage of the deprecated setup() style APIs throughout the doc
  2. document the new class_new() style APIs

Examples:

  1. max_jit_obex_free() is used in code at 20.1, 20.5, etc.
  2. There is no doc for max_jit_object_alloc()
  3. There is no doc for max_jit_object_free().
  4. No doc for class_extra_store(), class_extra_storeflags(), class_mess() in ext_obex.h
  5. No doc on how to use enum e_max_class_flags. Personally, I want to use CLASS_FLAG_DO_NOT_ZERO but I can't find any API in any header file that takes e_max_class_flags as a param
  6. conflict in the doc for object_free() in the extproto.h, PDF, and ext_obex.h. The first forward-references in freeobject() that "object_free() checkes to make sure the pointer is not NULL before trying to free it". However, the latter two have no notes that it does the NULL check. This is important to know for proper code and its optimization.

The SDK specifically deprecates max_jit_obex_free() and compiler warnings appear. However, there is no documentation to teach a dev what is the replacement.
WIth trial and error I was able to discover max_jit_object_free(x). However, I do not know if this API frees only the memory associated with the obex on x -or- if it free the obex memory and frees the memory block of x itself. I...think...that is only frees the obex memory.

tap commented

Thanks for the report. We are currently exploring some options for how to proceed with the SDK as we look to the future.

In some cases your concerns are caused by detritus in the header files that users will never need/want and in many cases won't even be exported by the Max application (e.g. item 4 in your list).

In the Jitter case, documentation has always been pretty sparse and I agree that it represents an area ripe for improvement.

Yes, object_free() does a NULL check. I was not aware that it was multiply-defined. Thanks for bringing that to our attention.

CLASS_FLAG_DO_NOT_ZERO is not used in any object by Cycling '74.

diablodale commented

got it. thank you.