kernel-doc comments have a prescribed format. This includes parenthesis
on the function name. To be _particularly_ correct we should also
capitalise the brief description and terminate it with a period.
In preparation for adding/updating kernel-doc function comments clean up
the ones currently present.
Signed-off-by: Tobin C. Harding <[email protected]>
---
lib/kobject.c | 43 ++++++++++++++++++++++---------------------
1 file changed, 22 insertions(+), 21 deletions(-)
diff --git a/lib/kobject.c b/lib/kobject.c
index 3eacd5b4643f..0181f102cd1c 100644
--- a/lib/kobject.c
+++ b/lib/kobject.c
@@ -18,7 +18,7 @@
#include <linux/random.h>
/**
- * kobject_namespace - return @kobj's namespace tag
+ * kobject_namespace() - Return @kobj's namespace tag.
* @kobj: kobject in question
*
* Returns namespace tag of @kobj if its parent has namespace ops enabled
@@ -36,7 +36,7 @@ const void *kobject_namespace(struct kobject *kobj)
}
/**
- * kobject_get_ownership - get sysfs ownership data for @kobj
+ * kobject_get_ownership() - Get sysfs ownership data for @kobj.
* @kobj: kobject in question
* @uid: kernel user ID for sysfs objects
* @gid: kernel group ID for sysfs objects
@@ -264,7 +264,7 @@ static int kobject_add_internal(struct kobject *kobj)
}
/**
- * kobject_set_name_vargs - Set the name of an kobject
+ * kobject_set_name_vargs() - Set the name of a kobject.
* @kobj: struct kobject to set the name of
* @fmt: format string used to build the name
* @vargs: vargs to format the string.
@@ -304,7 +304,7 @@ int kobject_set_name_vargs(struct kobject *kobj, const char *fmt,
}
/**
- * kobject_set_name - Set the name of a kobject
+ * kobject_set_name() - Set the name of a kobject.
* @kobj: struct kobject to set the name of
* @fmt: format string used to build the name
*
@@ -326,7 +326,7 @@ int kobject_set_name(struct kobject *kobj, const char *fmt, ...)
EXPORT_SYMBOL(kobject_set_name);
/**
- * kobject_init - initialize a kobject structure
+ * kobject_init() - Initialize a kobject structure.
* @kobj: pointer to the kobject to initialize
* @ktype: pointer to the ktype for this kobject.
*
@@ -382,7 +382,7 @@ static __printf(3, 0) int kobject_add_varg(struct kobject *kobj,
}
/**
- * kobject_add - the main kobject add function
+ * kobject_add() - The main kobject add function.
* @kobj: the kobject to add
* @parent: pointer to the parent of the kobject.
* @fmt: format to name the kobject with.
@@ -430,7 +430,8 @@ int kobject_add(struct kobject *kobj, struct kobject *parent,
EXPORT_SYMBOL(kobject_add);
/**
- * kobject_init_and_add - initialize a kobject structure and add it to the kobject hierarchy
+ * kobject_init_and_add() - Initialize a kobject structure and add it to
+ * the kobject hierarchy.
* @kobj: pointer to the kobject to initialize
* @ktype: pointer to the ktype for this kobject.
* @parent: pointer to the parent of this kobject.
@@ -457,7 +458,7 @@ int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
EXPORT_SYMBOL_GPL(kobject_init_and_add);
/**
- * kobject_rename - change the name of an object
+ * kobject_rename() - Change the name of an object.
* @kobj: object in question.
* @new_name: object's new name
*
@@ -524,7 +525,7 @@ int kobject_rename(struct kobject *kobj, const char *new_name)
EXPORT_SYMBOL_GPL(kobject_rename);
/**
- * kobject_move - move object to another parent
+ * kobject_move() - Move object to another parent.
* @kobj: object in question.
* @new_parent: object's new parent (can be NULL)
*/
@@ -577,7 +578,7 @@ int kobject_move(struct kobject *kobj, struct kobject *new_parent)
EXPORT_SYMBOL_GPL(kobject_move);
/**
- * kobject_del - unlink kobject from hierarchy.
+ * kobject_del() - Unlink kobject from hierarchy.
* @kobj: object.
*/
void kobject_del(struct kobject *kobj)
@@ -599,7 +600,7 @@ void kobject_del(struct kobject *kobj)
EXPORT_SYMBOL(kobject_del);
/**
- * kobject_get - increment refcount for object.
+ * kobject_get() - Increment refcount for object.
* @kobj: object.
*/
struct kobject *kobject_get(struct kobject *kobj)
@@ -692,7 +693,7 @@ static void kobject_release(struct kref *kref)
}
/**
- * kobject_put - decrement refcount for object.
+ * kobject_put() - Decrement refcount for object.
* @kobj: object.
*
* Decrement the refcount, and if 0, call kobject_cleanup().
@@ -721,7 +722,7 @@ static struct kobj_type dynamic_kobj_ktype = {
};
/**
- * kobject_create - create a struct kobject dynamically
+ * kobject_create() - Create a struct kobject dynamically.
*
* This function creates a kobject structure dynamically and sets it up
* to be a "dynamic" kobject with a default release function set up.
@@ -744,8 +745,8 @@ struct kobject *kobject_create(void)
}
/**
- * kobject_create_and_add - create a struct kobject dynamically and register it with sysfs
- *
+ * kobject_create_and_add() - Create a struct kobject dynamically and
+ * register it with sysfs.
* @name: the name for the kobject
* @parent: the parent kobject of this kobject, if any.
*
@@ -776,7 +777,7 @@ struct kobject *kobject_create_and_add(const char *name, struct kobject *parent)
EXPORT_SYMBOL_GPL(kobject_create_and_add);
/**
- * kset_init - initialize a kset for use
+ * kset_init() - Initialize a kset for use.
* @k: kset
*/
void kset_init(struct kset *k)
@@ -818,7 +819,7 @@ const struct sysfs_ops kobj_sysfs_ops = {
EXPORT_SYMBOL_GPL(kobj_sysfs_ops);
/**
- * kset_register - initialize and add a kset.
+ * kset_register() - Initialize and add a kset.
* @k: kset.
*/
int kset_register(struct kset *k)
@@ -838,7 +839,7 @@ int kset_register(struct kset *k)
EXPORT_SYMBOL(kset_register);
/**
- * kset_unregister - remove a kset.
+ * kset_unregister() - Remove a kset.
* @k: kset.
*/
void kset_unregister(struct kset *k)
@@ -851,7 +852,7 @@ void kset_unregister(struct kset *k)
EXPORT_SYMBOL(kset_unregister);
/**
- * kset_find_obj - search for object in kset.
+ * kset_find_obj() - Search for object in kset.
* @kset: kset we're looking in.
* @name: object's name.
*
@@ -899,7 +900,7 @@ static struct kobj_type kset_ktype = {
};
/**
- * kset_create - create a struct kset dynamically
+ * kset_create() - Create a struct kset dynamically.
*
* @name: the name for the kset
* @uevent_ops: a struct kset_uevent_ops for the kset
@@ -943,7 +944,7 @@ static struct kset *kset_create(const char *name,
}
/**
- * kset_create_and_add - create a struct kset dynamically and add it to sysfs
+ * kset_create_and_add() - Create a struct kset dynamically and add it to sysfs.
*
* @name: the name for the kset
* @uevent_ops: a struct kset_uevent_ops for the kset
--
2.21.0
On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> kernel-doc comments have a prescribed format. This includes parenthesis
> on the function name. To be _particularly_ correct we should also
> capitalise the brief description and terminate it with a period.
Ah, I didn't know that, sorry about that, my fault. I'll take patch 2
and 3 now in my tree, thanks!
greg k-h
On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> kernel-doc comments have a prescribed format. This includes parenthesis
> on the function name. To be _particularly_ correct we should also
> capitalise the brief description and terminate it with a period.
Why do think capitalisation and full stop is required for the function
description?
Sure, the example in the current doc happen to use that, but I'm not
sure that's intended as a prescription.
The old kernel-doc nano-HOWTO specifically did not use this:
https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
Johan
Adding Jon to CC
On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote:
> On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> > kernel-doc comments have a prescribed format. This includes parenthesis
> > on the function name. To be _particularly_ correct we should also
> > capitalise the brief description and terminate it with a period.
>
> Why do think capitalisation and full stop is required for the function
> description?
>
> Sure, the example in the current doc happen to use that, but I'm not
> sure that's intended as a prescription.
>
> The old kernel-doc nano-HOWTO specifically did not use this:
>
> https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
>
Oh? I was basing this on Documentation/doc-guide/kernel-doc.rst
Function documentation
----------------------
The general format of a function and function-like macro kernel-doc comment is::
/**
* function_name() - Brief description of function.
* @arg1: Describe the first argument.
* @arg2: Describe the second argument.
* One can provide multiple line descriptions
* for arguments.
I figured that was the canonical way to do kernel-doc function
comments. I have however refrained from capitalising and adding the
period to argument strings to reduce code churn. I figured if I'm
touching the line to add parenthesis then I might as well make it
perfect (if such a thing exists).
thanks,
Tobin.
On Thu, May 02, 2019 at 06:25:39PM +1000, Tobin C. Harding wrote: > Adding Jon to CC
>
> On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote:
> > On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> > > kernel-doc comments have a prescribed format. This includes parenthesis
> > > on the function name. To be _particularly_ correct we should also
> > > capitalise the brief description and terminate it with a period.
> >
> > Why do think capitalisation and full stop is required for the function
> > description?
> >
> > Sure, the example in the current doc happen to use that, but I'm not
> > sure that's intended as a prescription.
> >
> > The old kernel-doc nano-HOWTO specifically did not use this:
> >
> > https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
> >
>
> Oh? I was basing this on Documentation/doc-guide/kernel-doc.rst
>
> Function documentation
> ----------------------
>
> The general format of a function and function-like macro kernel-doc comment is::
>
> /**
> * function_name() - Brief description of function.
> * @arg1: Describe the first argument.
> * @arg2: Describe the second argument.
> * One can provide multiple line descriptions
> * for arguments.
>
> I figured that was the canonical way to do kernel-doc function
> comments. I have however refrained from capitalising and adding the
> period to argument strings to reduce code churn. I figured if I'm
> touching the line to add parenthesis then I might as well make it
> perfect (if such a thing exists).
I think you may have read too much into that example. Many of the
current function and parameter descriptions aren't even full sentences,
so sentence case and full stop doesn't really make any sense.
Looks like we discussed this last fall as well:
https://lkml.kernel.org/r/20180912093116.GC1089@localhost
Johan
On 5/2/19 6:40 PM, Tobin C. Harding wrote:
> On Thu, May 02, 2019 at 10:39:22AM +0200, Johan Hovold wrote:
>> On Thu, May 02, 2019 at 06:25:39PM +1000, Tobin C. Harding wrote: > Adding Jon to CC
>>>
>>> On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote:
>>>> On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
>>>>> kernel-doc comments have a prescribed format. This includes parenthesis
>>>>> on the function name. To be _particularly_ correct we should also
>>>>> capitalise the brief description and terminate it with a period.
>>>>
>>>> Why do think capitalisation and full stop is required for the function
>>>> description?
>>>>
>>>> Sure, the example in the current doc happen to use that, but I'm not
>>>> sure that's intended as a prescription.
>>>>
>>>> The old kernel-doc nano-HOWTO specifically did not use this:
>>>>
>>>> https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
>>>>
>>>
>>> Oh? I was basing this on Documentation/doc-guide/kernel-doc.rst
>>>
>>> Function documentation
>>> ----------------------
>>>
>>> The general format of a function and function-like macro kernel-doc comment is::
>>>
>>> /**
>>> * function_name() - Brief description of function.
>>> * @arg1: Describe the first argument.
>>> * @arg2: Describe the second argument.
>>> * One can provide multiple line descriptions
>>> * for arguments.
>>>
>>> I figured that was the canonical way to do kernel-doc function
>>> comments. I have however refrained from capitalising and adding the
>>> period to argument strings to reduce code churn. I figured if I'm
>>> touching the line to add parenthesis then I might as well make it
>>> perfect (if such a thing exists).
>>
>> I think you may have read too much into that example. Many of the
>> current function and parameter descriptions aren't even full sentences,
>> so sentence case and full stop doesn't really make any sense.
>>
>> Looks like we discussed this last fall as well:
>
> Ha, this was funny. By 'we' at first I thought you meant 'we the kernel
> community' but you actually meant we as in 'me and you'. Clearly you
> failed to convince me last time :)
>
>> https://lkml.kernel.org/r/20180912093116.GC1089@localhost
>
> I am totally aware this is close to code churn and any discussion is
> bikeshedding ... for me just because loads of places don't do this it
> still looks nicer to my eyes
>
> /**
> * sfn() - Super awesome function.
>
> than
>
> /**
> */ sfn() - super awesome function
>
> I most likely will keep doing these changes if I am touching the
> kernel-doc comments for other reasons and then drop the changes if the
> subsystem maintainer thinks its code churn.
>
> I defiantly won't do theses changes in GNSS, GREYBUS, or USB SERIAL.
>
> Oh, and I'm totally going to CC you know every time I flick one of these
> patches, prepare to get spammed :)
I have seen this discussion before also. And sometimes it is not even
a discussion -- it's more of an edict. To which I object/disagree.
The current (or past) comment style is perfectly fine IMO.
No caps needed. No ending '.' needed.
--
~Randy
On Thu, May 02, 2019 at 10:39:22AM +0200, Johan Hovold wrote:
> On Thu, May 02, 2019 at 06:25:39PM +1000, Tobin C. Harding wrote: > Adding Jon to CC
> >
> > On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote:
> > > On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> > > > kernel-doc comments have a prescribed format. This includes parenthesis
> > > > on the function name. To be _particularly_ correct we should also
> > > > capitalise the brief description and terminate it with a period.
> > >
> > > Why do think capitalisation and full stop is required for the function
> > > description?
> > >
> > > Sure, the example in the current doc happen to use that, but I'm not
> > > sure that's intended as a prescription.
> > >
> > > The old kernel-doc nano-HOWTO specifically did not use this:
> > >
> > > https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
> > >
> >
> > Oh? I was basing this on Documentation/doc-guide/kernel-doc.rst
> >
> > Function documentation
> > ----------------------
> >
> > The general format of a function and function-like macro kernel-doc comment is::
> >
> > /**
> > * function_name() - Brief description of function.
> > * @arg1: Describe the first argument.
> > * @arg2: Describe the second argument.
> > * One can provide multiple line descriptions
> > * for arguments.
> >
> > I figured that was the canonical way to do kernel-doc function
> > comments. I have however refrained from capitalising and adding the
> > period to argument strings to reduce code churn. I figured if I'm
> > touching the line to add parenthesis then I might as well make it
> > perfect (if such a thing exists).
>
> I think you may have read too much into that example. Many of the
> current function and parameter descriptions aren't even full sentences,
> so sentence case and full stop doesn't really make any sense.
>
> Looks like we discussed this last fall as well:
Ha, this was funny. By 'we' at first I thought you meant 'we the kernel
community' but you actually meant we as in 'me and you'. Clearly you
failed to convince me last time :)
> https://lkml.kernel.org/r/20180912093116.GC1089@localhost
I am totally aware this is close to code churn and any discussion is
bikeshedding ... for me just because loads of places don't do this it
still looks nicer to my eyes
/**
* sfn() - Super awesome function.
than
/**
*/ sfn() - super awesome function
I most likely will keep doing these changes if I am touching the
kernel-doc comments for other reasons and then drop the changes if the
subsystem maintainer thinks its code churn.
I defiantly won't do theses changes in GNSS, GREYBUS, or USB SERIAL.
Oh, and I'm totally going to CC you know every time I flick one of these
patches, prepare to get spammed :)
Cheers,
Tobin.
On Fri, May 03, 2019 at 11:40:15AM +1000, Tobin C. Harding wrote:
> On Thu, May 02, 2019 at 10:39:22AM +0200, Johan Hovold wrote:
> > On Thu, May 02, 2019 at 06:25:39PM +1000, Tobin C. Harding wrote: > Adding Jon to CC
> > >
> > > On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote:
> > > > On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> > > > > kernel-doc comments have a prescribed format. This includes parenthesis
> > > > > on the function name. To be _particularly_ correct we should also
> > > > > capitalise the brief description and terminate it with a period.
> > > >
> > > > Why do think capitalisation and full stop is required for the function
> > > > description?
> > > >
> > > > Sure, the example in the current doc happen to use that, but I'm not
> > > > sure that's intended as a prescription.
> > > >
> > > > The old kernel-doc nano-HOWTO specifically did not use this:
> > > >
> > > > https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
> > > >
> > >
> > > Oh? I was basing this on Documentation/doc-guide/kernel-doc.rst
> > >
> > > Function documentation
> > > ----------------------
> > >
> > > The general format of a function and function-like macro kernel-doc comment is::
> > >
> > > /**
> > > * function_name() - Brief description of function.
> > > * @arg1: Describe the first argument.
> > > * @arg2: Describe the second argument.
> > > * One can provide multiple line descriptions
> > > * for arguments.
> > >
> > > I figured that was the canonical way to do kernel-doc function
> > > comments. I have however refrained from capitalising and adding the
> > > period to argument strings to reduce code churn. I figured if I'm
> > > touching the line to add parenthesis then I might as well make it
> > > perfect (if such a thing exists).
> >
> > I think you may have read too much into that example. Many of the
> > current function and parameter descriptions aren't even full sentences,
> > so sentence case and full stop doesn't really make any sense.
> >
> > Looks like we discussed this last fall as well:
>
> Ha, this was funny. By 'we' at first I thought you meant 'we the kernel
> community' but you actually meant we as in 'me and you'. Clearly you
> failed to convince me last time :)
>
> > https://lkml.kernel.org/r/20180912093116.GC1089@localhost
>
> I am totally aware this is close to code churn and any discussion is
> bikeshedding ... for me just because loads of places don't do this it
> still looks nicer to my eyes
>
> /**
> * sfn() - Super awesome function.
>
> than
>
> /**
> */ sfn() - super awesome function
>
> I most likely will keep doing these changes if I am touching the
> kernel-doc comments for other reasons and then drop the changes if the
> subsystem maintainer thinks its code churn.
>
> I defiantly won't do theses changes in GNSS, GREYBUS, or USB SERIAL.
This isn't about any particular subsystem, but more the tendency of
people to make up random rules and try to to force it on others. It's
churn, and also makes things like code forensics and backports harder
for no good reason.
Both capitalisation styles are about as common for the function
description judging from a quick grep, but only 10% or so use a full
stop ('.'). And forcing the use of sentence case and full stop for
things like
/**
* maar_init() - Initialise MAARs.
or
* @instr: Operational instruction.
would be not just ugly, but wrong (as these are not independent
clauses).
Johan
On Fri 2019-05-03 09:56:07, Johan Hovold wrote:
> On Fri, May 03, 2019 at 11:40:15AM +1000, Tobin C. Harding wrote:
> > On Thu, May 02, 2019 at 10:39:22AM +0200, Johan Hovold wrote:
> > I am totally aware this is close to code churn and any discussion is
> > bikeshedding ... for me just because loads of places don't do this it
> > still looks nicer to my eyes
> >
> > /**
> > * sfn() - Super awesome function.
> >
> > than
> >
> > /**
> > */ sfn() - super awesome function
> >
> > I most likely will keep doing these changes if I am touching the
> > kernel-doc comments for other reasons and then drop the changes if the
> > subsystem maintainer thinks its code churn.
> >
> > I defiantly won't do theses changes in GNSS, GREYBUS, or USB SERIAL.
>
> This isn't about any particular subsystem, but more the tendency of
> people to make up random rules and try to to force it on others. It's
> churn, and also makes things like code forensics and backports harder
> for no good reason.
+1
But I could understand that it is hard to keep it as is when it bothers
ones eyes. I tend to change these things as well and have to activelly
stop myself again and again ;-)
Best Regards,
Petr
On Thu, 2 May 2019 18:46:16 -0700
Randy Dunlap <[email protected]> wrote:
> I have seen this discussion before also. And sometimes it is not even
> a discussion -- it's more of an edict. To which I object/disagree.
> The current (or past) comment style is perfectly fine IMO.
> No caps needed. No ending '.' needed.
For however much this matters...I really don't see that there needs to be
a rule one way or the other on this; the documentation serves its purpose
either way. I guess I see it like "British or American spelling";
there's nothing to drive a conversion in either direction.
jon
On Fri, May 03, 2019 at 09:56:07AM +0200, Johan Hovold wrote:
> On Fri, May 03, 2019 at 11:40:15AM +1000, Tobin C. Harding wrote:
> > On Thu, May 02, 2019 at 10:39:22AM +0200, Johan Hovold wrote:
> > > On Thu, May 02, 2019 at 06:25:39PM +1000, Tobin C. Harding wrote: > Adding Jon to CC
> > > >
> > > > On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote:
> > > > > On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> > > > > > kernel-doc comments have a prescribed format. This includes parenthesis
> > > > > > on the function name. To be _particularly_ correct we should also
> > > > > > capitalise the brief description and terminate it with a period.
> > > > >
> > > > > Why do think capitalisation and full stop is required for the function
> > > > > description?
> > > > >
> > > > > Sure, the example in the current doc happen to use that, but I'm not
> > > > > sure that's intended as a prescription.
> > > > >
> > > > > The old kernel-doc nano-HOWTO specifically did not use this:
> > > > >
> > > > > https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
> > > > >
> > > >
> > > > Oh? I was basing this on Documentation/doc-guide/kernel-doc.rst
> > > >
> > > > Function documentation
> > > > ----------------------
> > > >
> > > > The general format of a function and function-like macro kernel-doc comment is::
> > > >
> > > > /**
> > > > * function_name() - Brief description of function.
> > > > * @arg1: Describe the first argument.
> > > > * @arg2: Describe the second argument.
> > > > * One can provide multiple line descriptions
> > > > * for arguments.
> > > >
> > > > I figured that was the canonical way to do kernel-doc function
> > > > comments. I have however refrained from capitalising and adding the
> > > > period to argument strings to reduce code churn. I figured if I'm
> > > > touching the line to add parenthesis then I might as well make it
> > > > perfect (if such a thing exists).
> > >
> > > I think you may have read too much into that example. Many of the
> > > current function and parameter descriptions aren't even full sentences,
> > > so sentence case and full stop doesn't really make any sense.
> > >
> > > Looks like we discussed this last fall as well:
> >
> > Ha, this was funny. By 'we' at first I thought you meant 'we the kernel
> > community' but you actually meant we as in 'me and you'. Clearly you
> > failed to convince me last time :)
> >
> > > https://lkml.kernel.org/r/20180912093116.GC1089@localhost
> >
> > I am totally aware this is close to code churn and any discussion is
> > bikeshedding ... for me just because loads of places don't do this it
> > still looks nicer to my eyes
> >
> > /**
> > * sfn() - Super awesome function.
> >
> > than
> >
> > /**
> > */ sfn() - super awesome function
> >
> > I most likely will keep doing these changes if I am touching the
> > kernel-doc comments for other reasons and then drop the changes if the
> > subsystem maintainer thinks its code churn.
> >
> > I defiantly won't do theses changes in GNSS, GREYBUS, or USB SERIAL.
>
> This isn't about any particular subsystem, but more the tendency of
> people to make up random rules and try to to force it on others. It's
> churn, and also makes things like code forensics and backports harder
> for no good reason.
Points noted.
> Both capitalisation styles are about as common for the function
> description judging from a quick grep, but only 10% or so use a full
> stop ('.'). And forcing the use of sentence case and full stop for
> things like
>
> /**
> * maar_init() - Initialise MAARs.
>
> or
>
> * @instr: Operational instruction.
>
> would be not just ugly, but wrong (as these are not independent
> clauses).
You are correct here.
Thanks for taking the time to flesh out your argument Johan, I am now in
agreement with you :)
Cheers,
Tobin.
On Tue, May 07, 2019 at 09:00:35AM +1000, Tobin C. Harding wrote:
> On Fri, May 03, 2019 at 09:56:07AM +0200, Johan Hovold wrote:
> > This isn't about any particular subsystem, but more the tendency of
> > people to make up random rules and try to to force it on others. It's
> > churn, and also makes things like code forensics and backports harder
> > for no good reason.
>
> Points noted.
>
> > Both capitalisation styles are about as common for the function
> > description judging from a quick grep, but only 10% or so use a full
> > stop ('.'). And forcing the use of sentence case and full stop for
> > things like
> >
> > /**
> > * maar_init() - Initialise MAARs.
> >
> > or
> >
> > * @instr: Operational instruction.
> >
> > would be not just ugly, but wrong (as these are not independent
> > clauses).
>
> You are correct here.
Actually, I may have been wrong about the first example (imperative),
but the second still stands.
> Thanks for taking the time to flesh out your argument Johan, I am now in
> agreement with you :)
Good to hear! :)
Johan