Add documentation for legacy_param() in the header where it is defined

[frivoal]

See #21441

[jenshannoschwalm]

We have the dev-docs, i think such stuff should be there

[frivoal]

Does the text look reasonable otherwise? If so, I'll revise this PR to move it.

[jenshannoschwalm]

Does the text look reasonable otherwise?

Yes :-) pinging @kofa73 as he did most of the work on the dev-docs

[TurboGit]

Does the text look reasonable otherwise? If so, I'll revise this PR to move it.

Looks perfect to me too.

[TurboGit]

@frivoal : The documentation should probably be placed here:

https://github.com/darktable-org/darktable/blob/master/dev-doc/IOP_Module_API.md#legacy_params---upgrade-old-parameters

[kofa73]

Does the text look reasonable otherwise?

Yes :-) pinging @kofa73 as he did most of the work on the dev-docs

I think those comments look good; could @frivoal please simply add a sentence to the dev-docs mentioning the documentation you provided as a comment? There's no point repeating the same text in the docs, and your comment is clear. Maybe the importance of using calloc and dt_strlcpy_to_fixed is worth mentioning (they zero out the allocated memory, avoiding serializing random memory content, potentially sensitive data, to the DB / XMP) - and then the example in the docs must be updated, too, as it still uses malloc (see #21133, #21148). Let me know if you'd rather I do it.

[frivoal]

I'm sure you could do better, but I am happy to do it, as a small exercise on the way to get familiar with the code base. I appreciate if you can bear with me (and understand if you don't have the time and just want to be done with it).

I am a little unsure about how to balance comments in the header, vs in the sample useless.c, and whether https://github.com/darktable-org/darktable/blob/master/dev-doc/IOP_Module_API.md#legacy_params---upgrade-old-parameters should mention documentation in the code, or should be the documentation.

My intuition would be:

• dev-doc is for a high leve explanation of what exists and why you'd care
• .h is for precise information on how the function is actually invoked and what is expected of implementations
• useless.c is for supplemental info on how you might want to go about doing it

But for instance, are the calloc and dt_strlcpy_to_fixed comments an expectation, which should go in the header, or an implementation strategy which can live in the useless.c?

[kofa73]

I think .h would define the interface, what callers should know (how to use the function).

Since calloc and dt_strlcpy_to_fixed apply not only to legacy param migration, but to all cases where we allocate memory that could become seralized to disk, it may be worth adding them as a separate chapter in ... where exactly? New_Module_Guide.md could have such a section, but this applies to modifying existing modules, too. Should we add a Coding_Conventions.md or Security.md ? @TurboGit , @jenshannoschwalm , what do you think? I would actually think not only hard-core developers, but also people who work on the code using AI agents, would prefer one central source of info. On the other hand, hard-core devs may prefer C over markdown. :)

[jenshannoschwalm]

I think a Coding_Conventions.md should mention things like static leading underscore, indenting ...

Security.md or privacy.md ? Good point but not sure sure what should be in there.

Yes about "prefer one central source of info"

[wpferguson]

Should we add a Coding_Conventions.md or Security.md ?

Definitely Coding_Conventions.md.

I agree with @jenshannoschwalm about security.md and privacy.md. If darktable somehow becomes multi-user then maybe those documents would be useful.