Re: org-fold documentation

[Max Nikulin]

On 07/05/2022 11:15, Ihor Radchenko wrote:
> Vikas Rawal writes:
>
> > After upgrading to 9.5.3, I am getting warnings such as this, which I
> > suspect are due to org-fold.et.
> >
> > Warning (comp): org-fold.el:834:27: Warning: Unused lexical variable
> > `org-hide-macro-markers' Disable showing Disable logging
> > Warning (comp): org.el:76:30: Warning: Package cl is deprecated Disable
> > showing Disable logging
> > Warning (comp): ox.el:79:1: Warning: the function ‘org-back-to-heading’
> > might not be defined at runtime. Disable showing Disable logging
> > Warning (comp): ox.el:79:1: Warning: the function
> > ‘org-next-visible-heading’ might not be defined at runtime. Disable showing
> > Disable logging
> > Warning (comp): ox.el:79:1: Warning: the function ‘org-at-heading-p’ might
> > not be defined at runtime. Disable showing Disable logging
> >
> > Is org-fold.el documented already?

I see that org-fold-core.el has several screens of comments at the top 
of the file. Is it what you are asking for?

> > Any pointers to what might be causing
> > the above?
>
> These are native-comp warnings. They are not uncommon when
> native-compiling Org (not only org-fold.el) and generally harmless.
> If you are sufficiently annoyed with them, most of these warnings can be
> "fixed" by declaring the missing functions. The functions are available
> at runtime, but not during native-compilation.

The org-fold.el file has some `declare-function' forms. Do you mean it 
is just necessary to declare more names?

In c++ to speed-up compiling and to deal with circular dependence for 
declarations, there are some *_fwd.h header files with forward 
declarations. Such files are enough to make compiler aware that some 
word is a class, a type, or a function with arguments of certain types. 
They do not allow to allocate proper amount of space for an object and 
to construct it (it is necessary to "#include" full header for such 
purpose), but while e.g. a pointer is passed in the file to be compiled 
then nothing more is required.

Will it help to create files like org-fwd.el with function declarations 
to allow other packages (even from org-mode) to use "(require 
'org-fwd.el)" instead of adding a lot of `declare-function' forms that 
must be kept in sync with function definitions?

It is easier to notice new warnings introduced by changes when where 
were no warnings before.