Add API to write all items into buffer

[SUPERCILEX]

I have an expect test that checks for public API changes, but I currently have to dig into internals to get it working: https://github.com/SUPERCILEX/ftzz/blob/bc6779dd0b213f3c2c1150fb6ae8913674240815/tests/api.rs. It'd be nice to have an API that takes in a Write and spits out the items.

[Enselic]

Thank you for the feedback! Looks to me like you are using the API just as intended; you are not using internals. In fact, the code you use is the same as the example code at the top-level docs: https://docs.rs/public-api/latest/public_api/

I'm not sure it makes sense to have an even higher level wrapper, but I don't want to shoot down this idea before having seen a PR with a concrete proposal :)

[Emilgardis]

I think what could be done is moving cargo_public_api::Plain to public_api::Plain and placing the item formatter behind a impl fn

should be pretty straight forward

[Enselic]

@Emilgardis That would make public-api crate depend on terminal color crates, and I'd rather not have the public API analyzer depend on colors. I also try to avoid Cargo features (i.e. I don't want it an optional dependency), because I think that complicates code/testing/development/maintenance too much. So the current setup is quite deliberate.

But maybe there is some aspect of this I am overlooking, so if you want to prototype a bit around it, feel free of course!

[Emilgardis]

No it wouldn't as all the formatting would be controlled by the caller, it's possible to implement without any new dependencies!

[Enselic]

Sounds like you have thought this through, please go ahead, looking forward to the PR! 😀

[SUPERCILEX]

Oh I had no idea that was the intended use case :). I'm fine with the issue being closed though what I was basically thinking of doing is to make this method public and have it take in the Write as a param: https://github.com/Enselic/cargo-public-api/blob/6c84ec97a2c4d7e8137bd872bf6fe39906e3855f/public-api/src/main.rs#L57-L65

[Emilgardis]

yup, my initial comment is a bit unneccessary parsing through what is actually needed now, a convenience function like this makes sense.

[Enselic]

I'm actually not sure it makes sense to put that helper in the public API, because in the near future, we might want to make the output more tree-like, to solve #36, #37 and #39. The larger the API surface we have, the more work it will be to make necessary adaptations to the API. I try to keep the API surface minimal, because any addition to it, however small, increases maintenance burden of this project, and spare time is a scarce resource. Keep in mind that we not only have to maintain the API surface itself, but also tests for the API surface.

(Sorry for spreading some negativity again)

I'm fine with the issue being closed

If that is the case, and if @Emilgardis is also OK with that, I think we should do that.

Thanks again @SUPERCILEX for bringing this up so we could discuss it though.

[Emilgardis]

I'll implement what I have in mind and we can see if it makes sense, to me it doesn't bother me if it is not merged :)

[Emilgardis]

Aaaand thinking about this a bit more, I think this is more a documentation issue :D