[PATCH 5/5] drm/doc: Use new substruct support

[Jani Nikula]

On Tue, 20 Feb 2018, Thierry Reding <thierry.reding at gmail.com> wrote:
> On Mon, Feb 19, 2018 at 11:53:56PM +0100, Daniel Vetter wrote:
>> Note: This is untested because the new stuff hasn't landed in upstream
>> yet. But it should work.
>> 
>> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
>> ---
>>  include/drm/drm_vblank.h | 16 ++++++++++++++++
>>  1 file changed, 16 insertions(+)
>
> I couldn't find a reference to the new stuff, so maybe this was already
> discussed, but wouldn't it be possible for the parser to figure out the
> substruct by itself? That way the event. prefix could be avoided.

The short answer, supporting this format is a one-line change, while I'm
told anything else is harder.

Also, the format then is the same at all nesting levels, and you can do
any one of the three options below:

/**
 * struct foo - foo
 * @bar.baz: baz description, option 1 (support upstream)
 */
struct foo {
	/**
         * @bar.baz: baz description, option 2 (support in docs-next)
         */
	struct bar {
        	/**
	         * @bar.baz: baz description, option 3 (support in docs-next)
                 */
        	int baz;
        };
}

I don't deny it would be nice to be able to leave out the prefix when it
can be figured out from the context, but I'm not prepared to do the
work, and Mauro helpfully provided the patch for this approach, so it
seemed like the rational choice. See also [1] and [2].

BR,
Jani.


[1] http://mid.mail-archive.com/874lmjlfmg.fsf@intel.com
[2] http://mid.mail-archive.com/cover.1518788761.git.mchehab@s-opensource.com


-- 
Jani Nikula, Intel Open Source Technology Center