RFC kernel-doc: better handle data prototypes

Hi Jon,

Don't merge this series. It is just a heads on about what I'm working right now.

This is basically a proof of concept, not yet integrated with kernel-doc. It helps to show that investing on a tokenizer was a good idea.

I'm still testing the code.

Right now, kernel-doc logic to handle data types is very complex, and the code is split into dump_<type> functions, which in turn calls several ancillary routines. The most complex ones are related to handling struct, with involves converting inner struct/unions into members of the main struct.

By using this new code, all elements from most data types can be parsed with a single code.

Please notice that the code was designed to pick a single declaration, as this is how kdoc_parser will use it. If you try to parse multiple ones, the output won't be right, as it will pick the first declaration name and create a single item with all data declarations on it.

As it is not based on regexes, it can properly handle some problematic cases, like having:

    {};

and:

    ;;;;;

in the middle of a struct/union.

For enums, if one has values inside the declaration, like:

    enum { FOO, BAR } type;

It picks the right data type. Kernel-doc maps this currently as:
enum type

My plan is to integrate it at Kernel-doc and see how it goes. It will likely rise some corner cases, but, once we get it right, this will likely reduce the size and complexity of kdoc_parser.

If you want to test, you can use:

    ./parse_c.py

to use an example hardcoded on it, or it reads from a fname with:

    $ ./parse_c.py x.h
    CDataItem(decl_type=None, decl_name=None, parameterlist=['u16_data'], parametertypes={'u16_data': 'u16 u16_data[sizeof(u64) / sizeof(u16)]'})
    None None

parameterlist:
- u16_data

parametertypes:
- u16_data: u16 u16_data[sizeof(u64) / sizeof(u16)]

(on this example, x.h has just:

    u16 u16_data[sizeof(u64) / sizeof(u16)];

)

The logic stores decl_type and decl_name when the data is struct/union/enum. If the data is just a declaration, it fills only one element at parameterlist and at parametertypes.

Mauro Carvalho Chehab (2):
docs: kdoc: add a class to parse data items
HACK: add a parse_c.py file to test CDataParser

 parse_c.py                           |  87 +++++++++++
 tools/lib/python/kdoc/data_parser.py | 211 +++++++++++++++++++++++++++
 2 files changed, 298 insertions(+)
 create mode 100755 parse_c.py
 create mode 100644 tools/lib/python/kdoc/data_parser.py

2.53.0