We need to distribute the GtkDoc header generation script.
We need not to distribute the generated header, otherwise the VPATH
lookup would find the distributed one in $(srcdir) and try to update
it; but touching $(srcdir) is a bad thing.
For users a tag is <this> so the naming can be confusing.
The only exception where we probably shouldn't use the word symbol is the
"tags file" (*.tags) containing global tags - this has already the "tags"
extension and is more related to ctags and using "symbols file" is a bit
strange in this case.
As a result, the only places where this patch leaves the word "tag" are:
* phrase "tags file(s)"
* phrase "tags parser(s)"
* documentation mentioning the "tags" directory
* documentation mentioning the *.tags extension
and of course where it means the HTML/XML markup <thing>. The rest of the
uses of the word "tag" is replaced with "symbol".
Documentation is updated accordingly.
Fixes#579.
- split doxygen make recipe up
- rename geany_includedir to geany_gtkdocincludedir
- removed all references to geany-scintilla-gtkdoc.h
Also, remove geany-scintilla-gtkdoc.h from .gitignore
The script reads the doxygen xml output and generates two headers (optionally
a single header) that contains all of the plugin API in gtk-doc format.
Two headers because it's preferrable to group Scintilla related stuff
into its own namespace. This is a lot easier if g-ir-scanner can
work with a separate header file. If we change minds later on the script is
prepared to generate only one header.
A script will use the xml to generate a gtkdoc'ized header of the plugin API.
The xml files are also installed so that external users can use the xml
that corresponds to the installed version of Geany.
For now a separet doxyfile is used because the gtkdoc'ized header needs
a few types to be documented which not desired to be documented generally.
All of these typos were found by codespell, so credits go the
the authors of this incredibly useful tool.
I manually confirmed and adapted all changes, which includes
reflowing over-long lines or filling up with spaces for alignment.
Some of these typos may need forwarding to their original authors.
codespell reported a lot words where I am unsure; I have not
included those corrections.
Major changes are:
- Some types were accidentally documented, even though they couldn't be
accessed by any exported API functions. Those are removed (especially
from encodings.h).
- Some types were not documented where they should. Documentation is
added for them. Members are not necessarily documented separately if names
are self-explanatory.
- @a XXX refers to parameters of the function, it's inappropriate for
highlighting NULL (change to @c)
- As per consensus, build_info is removed from GeanyData (replaced by
pointer to avoid ABI break; added grep-able abi-todo tag so it doesn't get
forgotten)
Now that there is a proper user indication for the "maintain history on
reload" feature we can toggle it on by default. The setting is also renamed
so that the default is effective for everyone (this was the plan).
This function finally allows plugins to register themselves as a proxy
for one or more file extensions.
Lots of documentation is added to doc/plugins.dox, please refer to that for more
details.
Since geany_load_module() is called for non-enabled plugins you may not
use the plugin API here yet. The only exceptions to this rule are API functions
required for plugin registration.
This rule is hard to enforce (would need to g_return_if_val(PLUGIN_LOADED_OK(p))
for all API functions (well, those taking a plugin pointer anyway), so this
rule is only documented for now.
It was found that because geany_plugin_set_data() could be used by both
plugin's init() and geany_load_module(), that it introduced some uncertainty
as to when to call the free_func. init() callers might expect the call
around the same time as cleanup() is called, while geany_load_module()
callers expected the call at module unload time.
It was indeed called at module unload time. But that means that init() callers
cannot call it again reliably after in a init()->cleanup()->init() flow (when
toggling the plugin) without fully unloading the plugin (which is what we do
currently but that's we would want to change).
With the separation we can actually destroy the data depending on where
it was set and do everything unambigiously.
The documentation provides a quite detailed description of the new loader
In addition it adds a "how to transition" that briefly describes the old
loader (for curious newcomers) and lots of hints for porting legacy
plugins to the new loader.
We want it disabled by default in 1.25 for everyone, but want to be
able to get it back on by default later on when the UI is more
polished.
So we will need to have a way to tell whether the configuration comes
from 1.25 and should be upgraded or was willfully disabled by the user
in a later version. So, use a temporary setting name that defaults to
disabled for 1.25
See #553.
While the feature is nice, it might be unexpected and lacks user
feedback. This might lead to user thinking they lost their work
because they don't know they can undo the reload operation.
So, disable the feature by default until we introduce appropriate user
feedback allowing the user to learn about the feature and new behavior.
See http://lists.geany.org/pipermail/devel/2015-June/thread.html#9537
Add rest of headers needed for declarations of all public API
functions. Add HAVE_PLUGINS define to geanyplugins.h since some headers
need this and it should always be valid for this header.
geanyfunctions.h left for source-level backwards compatibility for
plugins which might `#include` this header directly. I don't know why
they do it, but some Geany-Plugins do this.
