Re: ✘example

[Joshua Judson Rosen]

On 3/6/21 9:06 PM, Gary E. Miller wrote:
> Yo All!
>
> This issue keeps coming up:
>
> https://gitlab.com/gpsd/gpsd/-/issues/126
>
> I think the source is several Stackoverflow answers that totally
> misunderstand gpsd.  Looking at one of them, they make the valid
> complaint that the libgps man page does not have a working example.

I don't know about the general audience, but I can speak for FoxtrotGPS,
which was called out in that but report.

The same person also field a bug in our tracker:

        https://bugs.launchpad.net/foxtrotgps/+bug/1917998

Maybe it's not _exactly_ the same issue on both ends, because
on your end he's pointing to the absence of a value in the _protocol stream_,
and on our end he's pointing to our use of a member in the gps_fix_t structure
in the API..., but:

I think our `misunderstanding' in FoxtrotGPS came from the comments in gps.h,
which we were looking at because it felt like the only practical
documentation that we had since there wasn't any description
of the data library structures in the libgps man page;
these lines in particular:

            /* GPS status -- always valid */
            int    status;              /* Do we have a fix? */
        #define STATUS_NO_FIX   0       /* no */

You say:

        "no status field" is perfectly normal in many configurations.
        [...]

        This statement was never, ever, true:

        "they assume that gpsdata.fix.status == 0 means no fix."

OK. I guess I have to read that as "the comments in gps.h have been
actively misleading us for the last decade" (that "always valid"
remark in particular directly contradicts everything that you just
wrote in that ticket that diego filed).

Thank you for for fixing it :)

As far as this remark goes:

        The man page shows "mode" is the proper way to check for a fix.

There isn't even a reference to that man page from the libgps man page,
and I could be wrong but I don't _think_ there even ever was.

If you want users of the library to go read the protocol docs,
at least point to the protocol docs from the API docs.

I think what you're trying to do right now with providing examples
is better, though; but really, just fixing the misleading remarks
in the header would have been enough for us.

Thanks again.

--
Connect with me on the GNU social network: 
<https://status.hackerposse.com/rozzin>
Not on the network? Ask me for an invitation to a social hub!