clarifications on the lifecycle of progress bars

[djugei]

There is currently multiple apparent ways to get rid of a progress bar:

• drop all references to it
• call reset()
• call finish()
• call finish_and_clear()
• call abandon()

even after reading the documentation i personally do not understand the difference between them, even though i am somewhat sure that reset() does not even belong in the list.

please clarify the lifecycle of a progress bar, what happens on drop and what the different finalizers do. also handle the special cases when you want to re-use that specific progressbar instance to display the progress of a different process and the case where the progressbar is part of a multiprogress.

also, apparently slightly related: more strongly differentiate prefix and message.

[djc]

What problem are you trying to solve? Which documentation have you tried to consume which failed to clarify things for you, and why?

[chris-laplante]

Related: #595

[djugei]

i am trying to display multiple progressbars to users, since this is hard to test for correctness i would like to build a solid mental model and get things right the first time.

i have read the top level crate documentation and the entire documentation on progressbar and multiprogress plus some others and have read and contributed some of the crates code.

specifically the documentation for the initially mentioned methods does, to my eye, not meaningfully differ, additionally it mainly restates the functions name, not so much what will actually happen on calling it. behaviour on drop is afaik undocumented.

[djc]

I'm sorry, I won't have time to go digging through the source code to clarify the lifecycle here. I suggest you spend some time looking at the implementation yourself and ask more specific questions about it if that doesn't clarify things enough.