GeanyLua: geany.fileinfo: Added a field for single-line comments; all 'comment' fields are renamed as in filetype definition files.

[Skif-off]

From discussion 4174.

It's really strange: we have information about multi-line comments, but no single-line comments. Let's fix this :)

[xiota]

Would "comment" instead of "single" be better?

[Skif-off]

Yes, sounds better. Fixed.

[b4n]

opener and closer sound real weird, but that's already there. But why not simply use the same name as Geany for this new one? So one day those other two weird names could also use a better one without having comment already there rendering things less clear. JMO.

[xiota]

If the plan is to eventually use the same names as Geany, should add all three now, comment_single, comment_open, comment_close... and note opener/closer as deprecated.

[Skif-off]

comment_open and comment_close sound clearer, but they are longer (this is a bit unusual for fields).

If the plan is to eventually use the same names as Geany, should add all three now

Changes will be mentioned in the list of changes on the releases page, but I do not know how many users look at the list of changes and will be able to adjust their scripts. On the other hand, new Geany versions are rarely released, and reviewing the list of changes cannot become a tedious chore :)
On the other hand, maintaining compatibility is traditionally considered a friendlier solution.
So, it seems to me that there is no urgent need to rename opener and closer.

About the length of the name: I thought of using comm instead of comment.

[xiota]

It's not about "urgent", but whether renaming the fields will or can be done at all. Would be good for someone with commit privileges to just make a decision.

The existing names are not self-explanatory and don't match the names used by Geany. Anyone using them would already have to check (and recheck) documentation for usage.

The main reasons to leave them alone are they're shorter and might be used in existing scripts. However, plugins and scripts often require user intervention with new releases, so the change wouldn't really be unexpected. Error messages would prompt users to check documentation for updates.

[Skif-off]

@xiota, what do you think about comm instead of comment?

[xiota]

comm would be worse than comment. Not self-explanatory, doesn't match Geany name, and less descriptive.

Upon further reflection, I now think field names should be switched entirely to the Geany name, immediately dropping the old names.

• Matching Geany names allows them to be found in either Geany or GeanyLua source or documentation.
• Potentially revising a few existing scripts is a minor inconvenience.
• Immediately dropping the old name allows both old and new name to be present within a single commit. If the old name were deprecated and dropped later, finding the new name in a several years old commit could be more challenging.

[Skif-off]

• There are several examples of abbreviated names.
• We can enter "desk", "ext" or "comm" faster than "description", "extension", "comment_open" or "comment_close".
• I do not know about the source code, but users will have to open the help in any case.

But you're the maintainer, so the final decision should be yours.

I changed it and if everything is okay, then I will merge the commits and correct the commit message.

[xiota]

There are these too...

SetTableStr("type",   FileTypeStr(name));
SetTableStr("desc",   FileTypeStr(title));
SetTableStr("comment", FileTypeStr(comment_single));

Too much to change... maybe should minimize changes and revert back. I'm going to think some more about it some more...

[xiota]

What about following (and associated doc change)? Everything else can stay as-is with no plans to further align names.

SetTableStr("comment_single", FileTypeStr(comment_single));

[Skif-off]

@xiota, so your final decision is

comment_single
comment_open
comment_close

?

[xiota]

I was having connection problems with github... I think comment_{single,open,close} would be good / final. It's more verbose than previously, but more clear what they are.

[Skif-off]

Everything seems to be done.

[xiota]

LGTM... Ready for @b4n review/action.

Tested with script...

fileinfo = geany.fileinfo()
if fileinfo then
  output = "geany.fileinfo()\n"
  output = output .. "name = " .. fileinfo['name'] .. "\n"
  output = output .. "path = " .. fileinfo['path'] .. "\n"
  output = output .. "ext = " .. fileinfo['ext'] .. "\n"
  output = output .. "type = " .. fileinfo['type'] .. "\n"
  output = output .. "desc = " .. fileinfo['desc'] .. "\n"
  output = output .. "comment_single = " .. fileinfo['comment_single'] .. "\n"
  output = output .. "comment_open = " .. fileinfo['comment_open'] .. "\n"
  output = output .. "comment_close = " .. fileinfo['comment_close'] .. "\n"
  output = output .. "action = " .. fileinfo['action'] .. "\n"
  output = output .. "ftid = " .. fileinfo['ftid'] .. "\n"
  output = output .. "encoding = " .. fileinfo['encoding'] .. "\n"

  if fileinfo['bom'] then
    output = output .. "bom = true\n"
  else
    output = output .. "bom = false\n"
  end

  if fileinfo['changed'] then
    output = output .. "changed = true\n"
  else
    output = output .. "changed = false\n"
  end

  if fileinfo['readonly'] then
    output = output .. "readonly = true\n"
  else
    output = output .. "readonly = false\n"
  end

  geany.status(output)
else
  geany.status("geany.fileinfo: nil")
end

[b4n]

LGTM if backward compatibility doesn't matter. Maybe mention it somewhere I'm the docs?

[Skif-off]

@b4n, the commit message will be in the list of changes, I don't know what else to add.

[b4n]

@Skif-off I probably would have added something like "this used to be named opener before 2.1", or added an upgrading to 2.1 section, but if it's no issue I don't mind and the NEWS might indeed be enough.

[Skif-off]

@b4n, I don't think that makes sense.
The new user will open the help and will see the new names. The old user will see the list of changes.
Or the user will see an error (if it uses this function) with the line number and position in the line and see the list of changes or immediately open the help...
Adding the "Incompatibilities with the previous version" section to the help seems redundant.

[xiota]

@elextr As the documentation expert... your opinion?

[elextr]

Sorry can't provide any help. Cheers

…

On Wed, 18 Jun 2025 at 06:43, xiota ***@***.***> wrote: *xiota* left a comment (geany/geany-plugins#1397) <#1397 (comment)> @elextr <https://github.com/elextr> As the documentation expert... your opinion? — Reply to this email directly, view it on GitHub <#1397 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAGGATOD2ZKB4BPHONQ5NBL3EB4VRAVCNFSM6AAAAABUMVX5TWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSOBRG43TQMBUGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[b4n]

@Skif-off OK if you think that's good it's fine