Re: [PATCH v8 4/7] scripts: add block-coroutine-wrapper.py

[Vladimir Sementsov-Ogievskiy]

24.09.2020 20:56, Eric Blake wrote:
> On 9/15/20 11:44 AM, Vladimir Sementsov-Ogievskiy wrote:
> > We have a very frequent pattern of creating coroutine from function
> > with several arguments:
>
> > +++ b/docs/devel/block-coroutine-wrapper.rst
> > @@ -0,0 +1,54 @@
> > +=======================
> > +block-coroutine-wrapper
> > +=======================
> > +
> > +A lot of functions in QEMJ block layer (see ``block/*``) can by called
>
> My editor italicized everhting after block/*...
>
> > +only in coroutine context. Such functions are normally marked by
> > +coroutine_fn specifier. Still, sometimes we need to call them from
> > +non-coroutine context, for this we need to start a coroutine, run the
> > +needed function from it and wait for coroutine finish in
> > +BDRV_POLL_WHILE() loop. To run a coroutine we need a function with one
> > +void* argument. So for each coroutine_fn function, which needs
>
> ...through void*.  I wonder if you need to use \* to let .rst know that these 
> are literal *, and not markup for a different font style. Although I did not 
> check the actual generated docs to see how they look.

Intuitively, `` should have greater priority than *.

I now check ./build/docs/devel/block-coroutine-wrapper.html , it looks OK:

   A lot of functions in QEMU block layer (see <code class="docutils literal notranslate"><span 
class="pre">block/*</span></code>) can only be

--
Best regards,
Vladimir