Aurélien Aptel <
address@hidden> schrieb am Sa., 26. Sep. 2015 um 16:56 Uhr:
How should module docstring be written? We either:
* pick a new syntax and teach make-docfile how to parse it. This is
the clean approach IMO, but it requires more work. We can use a
sufficiently simple syntax so that it can be embedded in comments in
other languages than C.
* define DEFVAR/DEFUN macro in module API header file to a noop so
that make-docfile can parse it as it is.
Library headers should respect namespace conventions. Because in C all symbols are global, it's important to pick names that are unlikely to clash. Usually this is done by prefixing all names with a string that is thought to be sufficiently unique, like "emacs" in your case. But DEFVAR/DEFUN don't follow that convention, so they can't be used in the header file.
There are some documentation frameworks available, e.g. Doxygen. It might be a good idea to use one of them instead of trying to define your own syntax.
As for the finalizer, I wanted to add a function in the API:
/* Finalizer prototype */
typedef int (*emacs_finalizer_function)(void *ptr);
emacs_value make_user_ptr (emacs_env *env,
void *ptr, emacs_finalizer_function *fin);
I still don't understand why we need finalizers. Using finalizers in languages without deterministic garbage collection is generally an antipattern.
Or we can have a full "method table" with printer function and other
things we might need in the future. Although It's a bit overkill with
just finalizer/printer...
/* Printer prototype */
typedef emacs_value (*emacs_printer_function)(void *ptr);
/* User-ptr operations */
typedef struct {
emacs_finalizer_function *fin;
emacs_printer_function *print;
/* ... */
} emacs_user_ptr_ops;
emacs_value make_user_ptr (emacs_env *env,
void *ptr, emacs_user_ptr_ops *ops);
What is the use case for this? Is the "user_ptr" functionality really needed?