Linux-Doc Archive on lore.kernel.org
 help / color / Atom feed
From: Lee Jones <lee.jones@linaro.org>
To: corbet@lwn.net
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: scripts/kernel-doc update
Date: Tue, 30 Jun 2020 10:36:40 +0100
Message-ID: <20200630093640.GK1179328@dell> (raw)

Good morning Jon, et al.,

Would someone be kind enough to update scripts/kernel-doc to elegantly
handle complex bitmap expressions in structures please?  Presently
only simple syntax is handled.  Something like:

struct foo {
       u8 arg : 10;
};

However, the bitmap is sometimes derived from some pre-processed
define or calculated.  Similar to the following examples.

Example 1:
---------

  File: drivers/misc/vmw_balloon.c

  struct vmballoon_batch_entry {
          u64 status : 5;
          u64 reserved : PAGE_SHIFT - 5;
          u64 pfn : 52;
  } __packed;

Example 2:
---------

  File: include/math-emu/single.h
  
  union _FP_UNION_S
  {
    float flt;
    struct {
  #if __BYTE_ORDER == __BIG_ENDIAN
      unsigned sign : 1;
      unsigned exp  : _FP_EXPBITS_S;
      unsigned frac : _FP_FRACBITS_S - (_FP_IMPLBIT_S != 0);
  #else
      unsigned frac : _FP_FRACBITS_S - (_FP_IMPLBIT_S != 0);
      unsigned exp  : _FP_EXPBITS_S;
      unsigned sign : 1;
  #endif
    } bits __attribute__((packed));
  };

The first example causes this warning:

 drivers/misc/vmw_balloon.c:262: warning: Function parameter or member '5' not described in 'vmballoon_batch_entry'

The second doesn't use kerneldoc, but is an example of a complex, but
totally possible/legitimate use-case.

Would it be feasible to make to make the regex which handles bitmaps
greedy up until the ';'?  Or perhaps someone can come up with
something more refined that would solve the problem.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

                 reply index

Thread overview: [no followups] expand[flat|nested]  mbox.gz  Atom feed

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200630093640.GK1179328@dell \
    --to=lee.jones@linaro.org \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Doc Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-doc/0 linux-doc/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-doc linux-doc/ https://lore.kernel.org/linux-doc \
		linux-doc@vger.kernel.org
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-doc


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git