@codebrainz, @elextr: the ProjectPrefs structure is actually not exposed to the plugin API therefore I agree to elextr and would like to keep the setter and getter function.

I tend to agree accessor functions are technically superior, I was just pointing out that it's different from most (all?) of the rest of the API. I have no objection to leaving the functions, only with the doc-comments not explaining properly what the functions do in isolation.

But I renamed the item project_session to use_project_session_files, renamed the function names to and extended the functions doc comment a bit. I hope that's sufficient.

I still have no idea what it does (without going to lookup that preference in the manual). Also it's probably not a good idea to refer to a private struct member in the public API. A good doc-comment can stand on its own to explain what it does, or at least refer to another thing in the API docs, IMO.

After looking in the manual for that preference, which I never realized (and don't understand why it) exists, what if it was something like:

/**
 * Controls whether currently opened files are stored in the project file.
 *
 * If @value is @c TRUE, this causes the opened files to be persisted when
 * the project is closed and re-opened, or when @c FALSE none of the
 * opened files will be re-opened when a project is re-opened.
 *
 * @param value Whether or not to persist the list of open files in the project file.
 * 
 * @see project_get_persist_open_files
 * @since 1.36 (240)
 */
void project_set_persist_open_files(gboolean value);

Whenever writing doc-comments, IMO it's best to imagine yourself a total n00b looking at the documentation for that one function without knowing anything else about the project's internals or other parts, and whether it would make any sense.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.