On Fri, 2017-09-29 at 22:32 +0200, Georg Chini wrote: > On 29.09.2017 16:03, Tanu Kaskinen wrote: > > On Sat, 2017-08-19 at 17:48 +0200, Georg Chini wrote: > > > --- > > > man/pactl.1.xml.in | 6 +++++ > > > man/pulse-cli-syntax.5.xml.in | 6 +++++ > > > shell-completion/bash/pulseaudio | 5 +++-- > > > shell-completion/zsh/_pulseaudio | 2 ++ > > > src/pulsecore/cli-command.c | 47 ++++++++++++++++++++++++++++++++++++++++ > > > src/utils/pacmd.c | 1 + > > > src/utils/pactl.c | 39 ++++++++++++++++++++++++++++++++- > > > 7 files changed, 103 insertions(+), 3 deletions(-) > > > > > > diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in > > > index 39569b6b..e868babc 100644 > > > --- a/man/pactl.1.xml.in > > > +++ b/man/pactl.1.xml.in > > > @@ -246,6 +246,12 @@ License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. > > > </p></optdesc> </option> > > > > > > <option> > > > + <p><opt>send-message</opt> <arg>RECIPIENT</arg> <arg>MESSAGE</arg> <arg>MESSAGE_PARAMETERS</arg></p> > > > + <optdesc><p>Send a message string to the specified recipient object. If applicable an additional string containing > > > + message parameters can be specified. A string is returned as a response to the message.</p></optdesc> > > > + </option> > > > > Are the message parameters expected to be just one string? I think it > > would be more user-frienly to allow the parameters to be split in > > multiple command line arguments. > > I don't understand what you mean. If you want to pass multiple parameters > you can do so with one string "param1=xyz param2=abc". In the end, the > message handler only receives one string and I do not see much difference > if you have to put the parameters in quotes or not. I think it's a significant difference in usability. Not a huge one, but still. We don't require quoting module parameter lists either, even though they're sent as a single string to the server. > Using one string leaves > you free to choose a separator between the parameters and it would also be > some more overhead to put the string together from multiple arguments. Do you plan to use some other separator than a space? Whatever the separator is, it should be used consistently rather than each message using different conventions. > > > > There should be a pointer to the place where all the messages are > > documented. > > > > We haven't agreed where to put the documentation. I think it would be > > highly desirable to have the documentation in the same repository with > > the code, so the wiki is probably not the best place. A plain text file > > would be the simplest way forward. The pactl man page could then point > > to the text file in cgit.freedesktop.org. > > I'm fine with this. Where do you think is the best place for the file? doc/messaging_api.txt > And what exactly should go in it? A list of possible messages with > arguments and an explanation what each argument does? Or also > some documentation on the message API functions? At minimum the documentation has to be usable as a reference for all messages and their parameters, but it would be good to also have a small introduction for people who are new to the subject. The C API functions don't need to be documented more than just mentioning them. Just add a pointer to the doxygen documentation. > > > > I think it would be a good idea to use something like Sphinx for > > generating nice html pages from plain text with some light markup, not > > only for the messaging API documentation but for other documentation as > > well. That requires some work to learn and configure the system, > > however, and while I expect it to be pretty simple, I'm probably not > > going to do that myself anytime soon. Would you be interested in > > working on that? Even if not, what do you think about using something > > like Sphinx for documentation? Would it be better than the wiki? Maybe > > I will some day find the time and motivation to set it up myself. > > I don't know Sphinx at all. I'll take a look at it, but at the moment > i do not have the time to start an additional documentation project. I heard of Sphinx[1] when the kernel moved its documentation to that system. I've got the impression that the developers have been quite happy with that change. Another system that I'm aware of is Hotdoc[2] that is apparently used by GStreamer and I think Gnome is moving its developer documentation to Hotdoc too. [1] http://www.sphinx-doc.org [2] https://hotdoc.github.io/ > > > > > > +static void string_callback(pa_context *c, const char *response, void *userdata) { > > > + if (!response) { > > > + pa_log(_("Failure: %s"), pa_strerror(pa_context_errno(c))); > > > > The callback is not called on failures, and there's nothing preventing > > the message handler from returning a null string as the response, so > > either you shouldn't treat a NULL response as a failure, or you should > > add documentation and some safeguards that prevent NULL responses from > > successful operations. > > Mh, the message handler is expected to return a string, if it returns > NULL, then this is an error. So what kind of safeguards do you mean? > A successful operation should always return a string. By safeguards I mean that introspect.c should reject NULL responses, and the server could have an assertion too. By documentation I mean that the pa_context_string_cb_t documentation should mention that the application can assume the response to be non-NULL. -- Tanu https://www.patreon.com/tanuk
