documents_array not exported

[codebrainz]

My Code-Format plugin uses the documents_array symbol, but this symbol is not exported to plugins anymore. Got an undefined symbol error for this in the Debug Messages. Adding GEANY_API_SYMBOL macro to documents_array in document.c fixes the issue.

This was always broken on Windows, and since the linkage-cleanup changes, on Linux too.

[elextr]

Can you not use document_find_by_id() as is recommended by the API docs?

But, as its documented to be in the API it looks simply like its a bug.

[codebrainz]

@elextr no, I need to loop over each document.

[elextr]

@codebrainz you could use the hated foreach macro then.

There is an argument to be made that given the semantics of the pointers in documents_array could be dangerous, since they can point to differing documents during their lifetime, it might be better to remove the array from the API instead, and leave the recommended document_find_by_id() as the only access.

[codebrainz]

document_find_by_id() doesn't allow you to iterate over the documents.

[elextr]

I said the foreach macro

[codebrainz]

The foreach_document() macro needs to access the documents array, if you remove access to the documents array, that macro can't work.

[elextr]

IIUC it uses a pointer hidden in another structure, not the direct access to the symbol.

[codebrainz]

It accesses geany_data->documents_array, yes, but that still gives access to the document pointers (ex. via the documents macro). It would be no safer with respect to the lifetime issues.

[elextr]

Oh, I misread it, it returns an index to the array, I read it as returning an ID, ok, we probably need a foreach_document_id macro.

[codebrainz]

I think we should just remove the global variables like this which are already accessible through geany_data from the plugin API (ie. remove the doc-comments, or move them to the geany_data member docs). They were already broken on Windows since the beginning and for a few versions on Linux and friends and it hasn't caused a huge outcry, so it's probably safe to do.

[b4n]

Can't you use GeanyData::documents_array instead of the global?

[b4n]

Okay, looks like we broke API at some point, but is it wise to re-add that when it's accessible through GeanyData?

[codebrainz]

No I don't think it's wise. I think we should just remove it('s docs) from the plugin API. It's cleaner to access it through geany_data, and the macro madness already uses that pointer anyway.

[kugel-]

It accesses geany_data->documents_array, yes, but that still gives access to the document pointers (ex. via the documents macro). It would be no safer with respect to the lifetime issues.

what life time issues? Since we are single threaded we can safely assume that documents don't go away during a loop

[codebrainz]

what life time issues?

If a plugin held on to a GeanyDocument pointer and a document was closed and one was opened, the GeanyDocument pointer might still point to a document but a different document. It's not an issue during loops, and exists for any function that gives access to a GeanyDocument, I'm just telling the issue @elextr is talking about.