Hi, I've thought of some more plugin API changes to improve consistency and/or organisation:
1. Make header names consistent - I've used ui_utils.h, plugin-symbols.c - probably they should just be uiutils.h, pluginsymbols.c.
2. Make editor functions take a GeanyEditor struct pointer. The editor fields of GeanyDocument could be moved into a separate struct, as the document struct is quite big, making it harder to locate fields. This is also good for an object-based design.
3. The document functions could take/return a GeanyDocument pointer instead of a document index, which would avoid the use of: documents[idx]-> being repeated all over the code base when doc-> is much neater. We would also need to update functions like msgwin_msg_add which take a idx parameter (this seems to be the only one at first glance).
This could be quite a big change, so it could be brought in gradually by having an additional p_documents field in GeanyFunctions, using a documents_ prefix for the new functions instead of document_. Once the changes are complete we could deprecate the old ones.
What do you think?
Regards, Nick
On Tue, 10 Jun 2008 13:10:30 +0100 Nick Treleaven nick.treleaven@btinternet.com wrote:
- The document functions could take/return a GeanyDocument pointer
instead of a document index, which would avoid the use of: documents[idx]-> being repeated all over the code base when doc-> is much neater.
I forgot to say, it would also mean much neater checks for an invalid document, just doc != NULL instead of DOC_IDX_VALID(idx) in most cases after using p_document->get_current().
Regards, Nick
On Tue, 10 Jun 2008 13:10:30 +0100, Nick Treleaven nick.treleaven@btinternet.com wrote:
Hi, I've thought of some more plugin API changes to improve consistency and/or organisation:
- Make header names consistent - I've used ui_utils.h,
plugin-symbols.c - probably they should just be uiutils.h, pluginsymbols.c.
I'm not sure. We could rename the plugin-symbols.c but do we need to rename ui_utils.h? I personally like the underscore because it is more readable than without even if it is a little harder to type.
- Make editor functions take a GeanyEditor struct pointer. The editor
fields of GeanyDocument could be moved into a separate struct, as the document struct is quite big, making it harder to locate fields. This is also good for an object-based design.
I agree.
- The document functions could take/return a GeanyDocument pointer
instead of a document index, which would avoid the use of: documents[idx]-> being repeated all over the code base when doc-> is much neater. We would also need to update functions like msgwin_msg_add which take a idx parameter (this seems to be the only one at first glance).
I forgot to say, it would also mean much neater checks for an invalid document, just doc != NULL instead of DOC_IDX_VALID(idx) in most cases after using p_document->get_current().
Yeah, that's the killer argument ;-). I like the idea even if it is a lot of work.
This could be quite a big change, so it could be brought in gradually by having an additional p_documents field in GeanyFunctions, using a documents_ prefix for the new functions instead of document_. Once the changes are complete we could deprecate the old ones.
Don't know if it is worth. I don't mind if the SVN version is broken for the one or another day. It's a development version and users should expect it to be broken.
Regards, Enrico
On Tue, 10 Jun 2008 15:09:41 +0200 Enrico Tröger enrico.troeger@uvena.de wrote:
On Tue, 10 Jun 2008 13:10:30 +0100, Nick Treleaven nick.treleaven@btinternet.com wrote:
...
- Make header names consistent - I've used ui_utils.h,
plugin-symbols.c - probably they should just be uiutils.h, pluginsymbols.c.
I'm not sure. We could rename the plugin-symbols.c but do we need to rename ui_utils.h? I personally like the underscore because it is more readable than without even if it is a little harder to type.
OK, so what should be the default naming style - we already have sciwrappers.h and recently documentprivate.h - should these also have underscores? Or maybe it doesn't matter?
- Make editor functions take a GeanyEditor struct pointer. The
editor fields of GeanyDocument could be moved into a separate struct, as the document struct is quite big, making it harder to locate fields. This is also good for an object-based design.
I agree.
Great, I'll probably do this after I start (3).
- The document functions could take/return a GeanyDocument pointer
instead of a document index, which would avoid the use of: documents[idx]-> being repeated all over the code base when doc-> is much neater. We would also need to update functions like msgwin_msg_add which take a idx parameter (this seems to be the only one at first glance).
I forgot to say, it would also mean much neater checks for an invalid document, just doc != NULL instead of DOC_IDX_VALID(idx) in most cases after using p_document->get_current().
Yeah, that's the killer argument ;-). I like the idea even if it is a lot of work.
This could be quite a big change, so it could be brought in gradually by having an additional p_documents field in GeanyFunctions, using a documents_ prefix for the new functions instead of document_. Once the changes are complete we could deprecate the old ones.
Don't know if it is worth. I don't mind if the SVN version is broken for the one or another day. It's a development version and users should expect it to be broken.
I think it can be done without breaking things - my first goal is to update the plugin API, so the core would be unaffected at first. I'll add a private Document::index field and then wrap the adapted document functions (which would use documents_) with the old document_ functions and idx usage. Then I'll update the core to use the new functions.
I'd thought maybe we could rename document.[hc] documents.[hc] - or would you prefer not to? I'm not sure but it might be more consistent with filetypes.c, using the plural rather than singular.
Regards, Nick
On Tue, 10 Jun 2008 16:51:59 +0100, Nick Treleaven nick.treleaven@btinternet.com wrote:
On Tue, 10 Jun 2008 15:09:41 +0200 Enrico Tröger enrico.troeger@uvena.de wrote:
On Tue, 10 Jun 2008 13:10:30 +0100, Nick Treleaven nick.treleaven@btinternet.com wrote:
...
- Make header names consistent - I've used ui_utils.h,
plugin-symbols.c - probably they should just be uiutils.h, pluginsymbols.c.
I'm not sure. We could rename the plugin-symbols.c but do we need to rename ui_utils.h? I personally like the underscore because it is more readable than without even if it is a little harder to type.
OK, so what should be the default naming style - we already have sciwrappers.h and recently documentprivate.h - should these also have underscores? Or maybe it doesn't matter?
Honestly, I don't care much. Yes, it would be nicer if they were all named using a unique scheme. But this causes renaming, changing files where the file names are used, may result in odd left-overs or other potential problems which aren't really necessary (ok, probably it's not that much work, but it is also not really a big problem at all). If you feel really uncomfortable with that, feel free to change it. If not, I don't care.
- The document functions could take/return a GeanyDocument
pointer instead of a document index, which would avoid the use of: documents[idx]-> being repeated all over the code base when doc-> is much neater. We would also need to update functions like msgwin_msg_add which take a idx parameter (this seems to be the only one at first glance).
I forgot to say, it would also mean much neater checks for an invalid document, just doc != NULL instead of DOC_IDX_VALID(idx) in most cases after using p_document->get_current().
Yeah, that's the killer argument ;-). I like the idea even if it is a lot of work.
This could be quite a big change, so it could be brought in gradually by having an additional p_documents field in GeanyFunctions, using a documents_ prefix for the new functions instead of document_. Once the changes are complete we could deprecate the old ones.
Don't know if it is worth. I don't mind if the SVN version is broken for the one or another day. It's a development version and users should expect it to be broken.
I think it can be done without breaking things - my first goal is to update the plugin API, so the core would be unaffected at first. I'll add a private Document::index field and then wrap the adapted document functions (which would use documents_) with the old document_ functions and idx usage. Then I'll update the core to use the new functions.
Ok, cool,
I'd thought maybe we could rename document.[hc] documents.[hc] - or would you prefer not to? I'm not sure but it might be more consistent with filetypes.c, using the plural rather than singular.
I remember I chose the singular 'document' (long time ago :D) based on the content this file should have: the document struct to represent an open document in Geany and related functions which work on one document 'object'. This were never really consistent done but mostly. And except for a few functions like document_close_all or document_open_files, this still applies, IMO. So, I would rather keep it as it is.
Regards, Enrico
On Tue, 10 Jun 2008 18:01:57 +0200 Enrico Tröger enrico.troeger@uvena.de wrote:
Honestly, I don't care much. Yes, it would be nicer if they were all named using a unique scheme. But this causes renaming, changing files where the file names are used, may result in odd left-overs or other potential problems which aren't really necessary (ok, probably it's not that much work, but it is also not really a big problem at all). If you feel really uncomfortable with that, feel free to change it. If not, I don't care.
OK, I'll leave it. Do you have any preference for any new files I might add in future: newfile.h new-file.h new_file.h? I guess the rule could be to use the first one unless the name is confusing, like uiutils would be - in those cases, use underscores. Probably I'll rename the plugin-symbols.c file as this seems to be the exception, as tm_source_file.h uses underscores.
...
I'd thought maybe we could rename document.[hc] documents.[hc] - or would you prefer not to? I'm not sure but it might be more consistent with filetypes.c, using the plural rather than singular.
I remember I chose the singular 'document' (long time ago :D) based on the content this file should have: the document struct to represent an open document in Geany and related functions which work on one document 'object'. This were never really consistent done but mostly. And except for a few functions like document_close_all or document_open_files, this still applies, IMO. So, I would rather keep it as it is.
OK, no problem.
Regards, Nick
On Wed, 11 Jun 2008 18:03:37 +0100, Nick Treleaven nick.treleaven@btinternet.com wrote:
On Tue, 10 Jun 2008 18:01:57 +0200 Enrico Tröger enrico.troeger@uvena.de wrote:
Honestly, I don't care much. Yes, it would be nicer if they were all named using a unique scheme. But this causes renaming, changing files where the file names are used, may result in odd left-overs or other potential problems which aren't really necessary (ok, probably it's not that much work, but it is also not really a big problem at all). If you feel really uncomfortable with that, feel free to change it. If not, I don't care.
OK, I'll leave it. Do you have any preference for any new files I might add in future: newfile.h new-file.h new_file.h? I guess the rule could be to use the first one unless the name is confusing, like uiutils would be - in those cases, use underscores. Probably I'll
This what I thought. As long as it stays readable, no separation characters, and otherwise, use an underscore. That's what I'd prefer.
rename the plugin-symbols.c file as this seems to be the exception, as tm_source_file.h uses underscores.
yeah.
Regards, Enrico
Hi, This is an update for anyone that hasn't looked at the new SVN branch.
On Tue, 10 Jun 2008 16:51:59 +0100 Nick Treleaven nick.treleaven@btinternet.com wrote:
- The document functions could take/return a GeanyDocument
pointer instead of a document index, which would avoid the use of: documents[idx]->
This code is now in the SVN branches/document-pointer directory, and will be merged probably next week, after some related things have been done.
...
This could be quite a big change, so it could be brought in gradually by having an additional p_documents field in GeanyFunctions, using a documents_ prefix for the new functions instead of document_. Once the changes are complete we could deprecate the old ones.
I changed my mind - I don't think we should have both p_document and p_documents - this just delays when we break plugins, and if we did that we'd still have to break the ABI to remove p_documents. The idea was also to rename the document_ prefix documents_, but this won't be done now (see earlier mails in this thread).
I think it can be done without breaking things - my first goal is to update the plugin API, so the core would be unaffected at first. I'll add a private Document::index field and then wrap the adapted document functions
This field is now public - GeanyDocument::index. This might make porting easier, and may be useful in other ways.
Regards, Nick