Re: [PATCH V4 4/8] libgpiod: Add rust wrapper crate

[Kent Gibson <warthog618@gmail.com>]

On Mon, Aug 01, 2022 at 05:35:06PM +0530, Viresh Kumar wrote:
> On 27-07-22, 18:08, Kent Gibson wrote:
> > On Wed, Jul 27, 2022 at 02:37:01PM +0530, Viresh Kumar wrote:
> > > On 27-07-22, 10:57, Kent Gibson wrote:
> > > > On Fri, Jul 08, 2022 at 05:04:57PM +0530, Viresh Kumar wrote:
> > > > Consider modules and namespaces rather than lumping everything in
> > > > the gpiod space.
> > > > 
> > > > e.g. gpiod::ChipInfo -> gpiod::chip::Info
> > > 
> > > The modules are already there, as file names. So what we really have is
> > > gpiod::chip_info::ChipInfo (yeah it isn't great for sure). But then it looked
> > > tougher/complex/unnecessary for end users to know the internals of a dependency
> > > and so I did this:
> > > 
> > > pub use crate::chip::*;
> > > pub use crate::edge_event::*;
> > > pub use crate::event_buffer::*;
> > > pub use crate::info_event::*;
> > > pub use crate::line_config::*;
> > > pub use crate::line_info::*;
> > > pub use crate::line_request::*;
> > > pub use crate::request_config::*;
> > > 
> > > which puts everything under gpiod::*. I think it is easier for users that way.
> > > The modules are fine for in-crate management, but for end user they shouldn't be
> > > visible.
> > > 
> > 
> > The main problem I have with putting everything in the top level is the
> > generated docs.  You get everything dumped on you, so all structs, enums
> > and functions, and it isn't clear to the user what the logical starting
> > point is.
> > If things are tiered then you can introduce them more gradually, or keep
> > them out of their way if they are unlikely to use them (e.g. ChipInfo,
> > InfoEvent).
> 
> I am not sure what to do about this. I was suggested earlier to dump it all at
> the top level namespace so it is easier/shorter for users, which also won't need
> to know the internal namespaces/modules of libgpiod.
> 

libgpiod has no namespaces/modules - cos it is C.
The users do need to understand how things fit together, and the flat
namespace doesn't help there - everything is equal.

True, "_" is shorter than "::".  Can't argue with that ;-).

In Rust the user can rename the import whatever they want, so I'm not sure
the "easier/shorter" argument holds much water.

> Looking at structures, there are just 8 of them which are exposed in docs now,
> which isn't a lot really. And then we have 12 enums now.
> 

This isn't a question of numbers, it is a question of whether to
indicate structure, or to flatten everything.

I find the structured approach both clearer and more idiomatic in Rust,
so that gets my vote.

Cheers,
Kent.