[hawkmoth] Re: [PATCH 08/13] hawkmoth: filter non documentation comments early on
- From: Jani Nikula <jani@xxxxxxxxxx>
- To: Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>, hawkmoth@xxxxxxxxxxxxx
- Date: Sat, 12 Jan 2019 11:03:24 +0200
On Tue, 08 Jan 2019, Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx> wrote:
On 1/8/19 10:30 PM, Jani Nikula wrote:
On Tue, 08 Jan 2019, Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
wrote:
Discarding comments that are not documentation early on saves a few
repeated lines of code later on in the recursive part of the comment
parser and a few dud iterations.
I didn't test... but does this change the behaviour for things like:
/**
* top level documentation comment
*/
/* meh */
int some_undocumented_function(void);
where the /* meh */ comment prevents the top level comment from becoming
documentation for the next cursor.
As it currently stands, the answer to the question is yes: the top level
comment is made top level, the function is undocumented, which is what I
would expect.
Agreed on the expectation.
Is there a scenario where you'd like to have the opposite?
With the above code example, no.
But I do wonder if we need a way to force a comment to be top level
comment (*) and detach it from the following token, *without* the need
to add a "workaround" plain comment. Imagine a header file with:
/**
* The xyzzy module.
*/
#ifndef XYZZY
#define XYZZY
I think the documentation comment would be attached to the include
protection. You'll have to add /**/ to break that.
Just something to think about, but since there's a way around this, it's
definitely not a pressing issue.
(*) I don't necessarily agree with the name "top level comment", it's
just something I used and stuck with. We can still change. Generic
comment? Module comment? File comment?
We probably should add a 'composition test' for cases like this.
Agreed.
BR,
Jani.
Cheers
--
Bruno Santos
PGP KEY: 941052CD (pool.sks-keyservers.net)
Other related posts:
