Re: [PATCH 1/2] ios: document ios_get_dev{,_if} in ios.h

[Jose E. Marchesi]

Hi Mohammad.

Thanks for the patch.

> 2023-04-30  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
>
>       * libpoke/ios.h (ios_get_dev_if): Add declaration.
>       (ios_get_dev): Likewise.
>       * libpoke/ios.c (ios_get_dev_if): Add `const' to function def.
>       * libpoke/ios-dev.h (ios_dev_if): Likewise.
> ---
>  ChangeLog         |  7 +++++++
>  libpoke/ios-dev.h |  2 +-
>  libpoke/ios.c     |  2 +-
>  libpoke/ios.h     | 12 ++++++++++++
>  4 files changed, 21 insertions(+), 2 deletions(-)
>
> diff --git a/ChangeLog b/ChangeLog
> index d1fee099..343a6e9f 100644
> --- a/ChangeLog
> +++ b/ChangeLog
> @@ -1,3 +1,10 @@
> +2023-04-30  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
> +
> +     * libpoke/ios.h (ios_get_dev_if): Add declaration.
> +     (ios_get_dev): Likewise.
> +     * libpoke/ios.c (ios_get_dev_if): Add `const' to function def.
> +     * libpoke/ios-dev.h (ios_dev_if): Likewise.
> +
>  2023-04-29  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
>  
>       * libpoke/ios-dev.h (struct ios_dev_if): Remove `data' field.
> diff --git a/libpoke/ios-dev.h b/libpoke/ios-dev.h
> index 6402983f..fe24fd23 100644
> --- a/libpoke/ios-dev.h
> +++ b/libpoke/ios-dev.h
> @@ -89,4 +89,4 @@ struct ios_dev_if
>     used by IOD implementations.  */
>  
>  extern void *ios_get_dev (ios ios);
> -extern struct ios_dev_if *ios_get_dev_if (ios ios);
> +extern const struct ios_dev_if *ios_get_dev_if (ios ios);
> diff --git a/libpoke/ios.c b/libpoke/ios.c
> index ed1d99d4..fe7ace47 100644
> --- a/libpoke/ios.c
> +++ b/libpoke/ios.c
> @@ -1650,7 +1650,7 @@ ios_get_dev (ios ios)
>    return ios->dev;
>  }
>  
> -struct ios_dev_if *
> +const struct ios_dev_if *
>  ios_get_dev_if (ios ios)
>  {
>    return ios->dev_if;
> diff --git a/libpoke/ios.h b/libpoke/ios.h
> index e06c97c3..0ef62693 100644
> --- a/libpoke/ios.h
> +++ b/libpoke/ios.h
> @@ -203,6 +203,18 @@ int ios_get_id (ios io);
>  
>  const char *ios_get_dev_if_name (ios io);
>  
> +/* Return the device interface.

I think "Return the IOD interface implementing the IO devices operated
by the given IO space." would be more informative here.


> +
> +   Please keep this in-sync with declarations in ios-dev.  */

What do you mean with that?

> +
> +const struct ios_dev_if *ios_get_dev_if (ios ios);
> +
> +/* Return the device instance.
> +
> +   Please keep this in-sync with declarations in ios-dev.  */
> +

I think "Return the IO device instance operated by the given IO space."
would be more informative here.

> +void *ios_get_dev (ios ios);
> +
>  /* Return the first IO space.  */
>  
>  ios ios_begin (void);