API docs: notmuch_database_open_with_config with NULL config

API docs: notmuch_database_open_with_config with NULL config

[James Cook]

Hi list,

If I'm not mistaken, calling notmuch_database_open_with_config with
config_path = NULL causes notmuch to try to find the config file
automatically.

It would be nice if that were documented in the notmuch(3) man page. I
can try drafting a patch if that would help.

(This message brought to you by trying to understand neomutt's notmuch
code...)

-- 
James

Re: API docs: notmuch_database_open_with_config with NULL config

[David Bremner]

James Cook <falsifian@falsifian.org> writes:

> Hi list,
>
> If I'm not mistaken, calling notmuch_database_open_with_config with
> config_path = NULL causes notmuch to try to find the config file
> automatically.
>
> It would be nice if that were documented in the notmuch(3) man page. I
> can try drafting a patch if that would help.
>
> (This message brought to you by trying to understand neomutt's notmuch
> code...)

Here is what i see in the notmuch(3) man page:

        config_path Path to config file.

           Config file is key-value, with mandatory sections. See notmuch-config(5) for more
           information. The key-value pair overrides the corresponding configuration data stored in the
           database (see notmuch_database_get_config)

           If config_path is NULL use the path specified

           • in environment variable NOTMUCH_CONFIG, if non-empty

           • by XDG_CONFIG_HOME/notmuch/ where XDG_CONFIG_HOME defaults to '$HOME/.config'.

           • by $HOME/.notmuch-config

           If config_path is '' (empty string) then do not open any configuration file.
           profile Name of profile (configuration/database variant).

           If non-NULL, append to the directory / file path determined for config_path and
           database_path.

           If NULL then use

           • environment variable NOTMUCH_PROFILE if defined,

           • otherwise 'default' for directories and '' (empty string) for paths.

I'm not claiming the documentation is perfect, but it seems to be
documented? Is there maybe some version skew between your man pages and
library?

d\r

Re: API docs: notmuch_database_open_with_config with NULL config

[James Cook]

On Sat, Apr 15, 2023 at 12:26:33PM -0300, David Bremner wrote:
> James Cook <falsifian@falsifian.org> writes:
> 
> > Hi list,
> >
> > If I'm not mistaken, calling notmuch_database_open_with_config with
> > config_path = NULL causes notmuch to try to find the config file
> > automatically.
> >
> > It would be nice if that were documented in the notmuch(3) man page. I
> > can try drafting a patch if that would help.
> >
> > (This message brought to you by trying to understand neomutt's notmuch
> > code...)
> 
> Here is what i see in the notmuch(3) man page:
> 
>         config_path Path to config file.
> 
>            Config file is key-value, with mandatory sections. See notmuch-config(5) for more
>            information. The key-value pair overrides the corresponding configuration data stored in the
>            database (see notmuch_database_get_config)
> 
>            If config_path is NULL use the path specified
> 
>            • in environment variable NOTMUCH_CONFIG, if non-empty
> 
>            • by XDG_CONFIG_HOME/notmuch/ where XDG_CONFIG_HOME defaults to '$HOME/.config'.
> 
>            • by $HOME/.notmuch-config
> 
>            If config_path is '' (empty string) then do not open any configuration file.
>            profile Name of profile (configuration/database variant).
> 
>            If non-NULL, append to the directory / file path determined for config_path and
>            database_path.
> 
>            If NULL then use
> 
>            • environment variable NOTMUCH_PROFILE if defined,
> 
>            • otherwise 'default' for directories and '' (empty string) for paths.
> 
> I'm not claiming the documentation is perfect, but it seems to be
> documented? Is there maybe some version skew between your man pages and
> library?
> 
> d

Oops, I have that too.

I didn't realize there was further documentation after the summary in
the "Functions" section. This is much better! Thanks.

It is possible that a short note indicating that detailed descriptions
will follow, placed at the top of the man page and/or at the top of the
"Functions" section, would have saved me from my impatience. I think I
do tend to read the first sentence or two of a man page before just
searching for what I'm looking for. But absent such a note, maybe I can
be excused for paging through a few screenfuls of API summary and
assuming that's all there was.

-- 
James\r

Re: API docs: notmuch_database_open_with_config with NULL config

[David Bremner]

James Cook <falsifian@falsifian.org> writes:

> It is possible that a short note indicating that detailed descriptions
> will follow, placed at the top of the man page and/or at the top of the
> "Functions" section, would have saved me from my impatience. I think I
> do tend to read the first sentence or two of a man page before just
> searching for what I'm looking for. But absent such a note, maybe I can
> be excused for paging through a few screenfuls of API summary and
> assuming that's all there was.

I'm a bit reluctant to invest much effort in the current Doxygen based
API docs (I'm hoping we eventually replace them with something more
compatible with the rest of the sphinx-doc based documentation). On the
other hand if someone else out there is a better Doxygen wrangler than I
and the fix is relatively small, I don't see why we wouldn't apply that
change.

d