| Message ID | 1408366982-14102-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Rejected |
| Headers | show |
On 08/18/2014 04:03 PM, Mike Holmes wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > CONTRIBUTING | 13 +++++++++++++ > 1 file changed, 13 insertions(+) > > diff --git a/CONTRIBUTING b/CONTRIBUTING > index 08887de..91e2aa9 100644 > --- a/CONTRIBUTING > +++ b/CONTRIBUTING > @@ -49,6 +49,19 @@ compiler: > Please ensure submitted patches are checkpatch clean before submitting > them to avoid having them automatically returned for rework. > > +Documenting the code > + > +Allow doxygen to use all its default behaviors to identify tagged information but where a doxygen tag must be specified use @ > +The first line is by default the brief summary. > +The next paragraph is by default the detailed summary > +Normal comment sections should be before the code block and start with /** on its own line and finish with */ on its own line. Is it a mandatory requirement to have /** on its own line if description fits in one line? /** macro description */ #define SOME_MACRO 0 > +Commenting on the end of a line for #defines and struct members is allowed using /**< <text> */ > +Files should start with a files description using @file > +Functions should specify their parameters with @param[in] and @param[out] > +Functions return values should all be specified using @return > +There should be no doxygen warnings or errors generated. > + > + > [1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle > [2] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches > [3] refer to README file. >
On 20 August 2014 17:31, Taras Kondratiuk <taras.kondratiuk@linaro.org> wrote: > On 08/18/2014 04:03 PM, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > > --- > > CONTRIBUTING | 13 +++++++++++++ > > 1 file changed, 13 insertions(+) > > > > diff --git a/CONTRIBUTING b/CONTRIBUTING > > index 08887de..91e2aa9 100644 > > --- a/CONTRIBUTING > > +++ b/CONTRIBUTING > > @@ -49,6 +49,19 @@ compiler: > > Please ensure submitted patches are checkpatch clean before > submitting > > them to avoid having them automatically returned for rework. > > > > +Documenting the code > > + > > +Allow doxygen to use all its default behaviors to identify tagged > information but where a doxygen tag must be specified use @ > > +The first line is by default the brief summary. > > +The next paragraph is by default the detailed summary > > +Normal comment sections should be before the code block and start with > /** on its own line and finish with */ on its own line. > > Is it a mandatory requirement to have /** on its own line if > description fits in one line? > > /** macro description */ > #define SOME_MACRO 0 > No it is not, you can use the format below - Commenting on the end of a line for #defines and struct members is allowed using /**< <text> */ > > > +Commenting on the end of a line for #defines and struct members is > allowed using /**< <text> */ > > +Files should start with a files description using @file > > +Functions should specify their parameters with @param[in] and > @param[out] > > +Functions return values should all be specified using @return > > +There should be no doxygen warnings or errors generated. > > + > > + > > [1] > https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle > > [2] > https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches > > [3] refer to README file. > > > > > -- > Taras Kondratiuk >
On 08/21/2014 12:43 AM, Mike Holmes wrote: > > > > On 20 August 2014 17:31, Taras Kondratiuk <taras.kondratiuk@linaro.org > <mailto:taras.kondratiuk@linaro.org>> wrote: > > On 08/18/2014 04:03 PM, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org > <mailto:mike.holmes@linaro.org>> > > --- > > CONTRIBUTING | 13 +++++++++++++ > > 1 file changed, 13 insertions(+) > > > > diff --git a/CONTRIBUTING b/CONTRIBUTING > > index 08887de..91e2aa9 100644 > > --- a/CONTRIBUTING > > +++ b/CONTRIBUTING > > @@ -49,6 +49,19 @@ compiler: > > Please ensure submitted patches are checkpatch clean before > submitting > > them to avoid having them automatically returned for rework. > > > > +Documenting the code > > + > > +Allow doxygen to use all its default behaviors to identify > tagged information but where a doxygen tag must be specified use @ > > +The first line is by default the brief summary. > > +The next paragraph is by default the detailed summary > > +Normal comment sections should be before the code block and > start with /** on its own line and finish with */ on its own line. > > Is it a mandatory requirement to have /** on its own line if > description fits in one line? > > /** macro description */ > #define SOME_MACRO 0 > > > No it is not, you can use the format below - Commenting on the end of a > line for #defines and struct members is allowed using /**< <text> */ So according to description both cases below are ok: /** * macro description */ #define SOME_MACRO 0 #define SOME_MACRO 0 /**< macro description */ It was asking about a third form, which seems to be acceptable for doxygen, but not mentioned in this patch: /** macro description */ #define SOME_MACRO 0
Ok, I think I understand now - hope I do anyway :) Yes, I think this is fine too, unless there is objection I will add this explicitly to the patch. /** macro description */ #define SOME_MACRO 0 On 21 August 2014 08:59, Taras Kondratiuk <taras.kondratiuk@linaro.org> wrote: > On 08/21/2014 12:43 AM, Mike Holmes wrote: > >> >> >> >> On 20 August 2014 17:31, Taras Kondratiuk <taras.kondratiuk@linaro.org >> <mailto:taras.kondratiuk@linaro.org>> wrote: >> >> On 08/18/2014 04:03 PM, Mike Holmes wrote: >> > Signed-off-by: Mike Holmes <mike.holmes@linaro.org >> <mailto:mike.holmes@linaro.org>> >> >> > --- >> > CONTRIBUTING | 13 +++++++++++++ >> > 1 file changed, 13 insertions(+) >> > >> > diff --git a/CONTRIBUTING b/CONTRIBUTING >> > index 08887de..91e2aa9 100644 >> > --- a/CONTRIBUTING >> > +++ b/CONTRIBUTING >> > @@ -49,6 +49,19 @@ compiler: >> > Please ensure submitted patches are checkpatch clean before >> submitting >> > them to avoid having them automatically returned for rework. >> > >> > +Documenting the code >> > + >> > +Allow doxygen to use all its default behaviors to identify >> tagged information but where a doxygen tag must be specified use @ >> > +The first line is by default the brief summary. >> > +The next paragraph is by default the detailed summary >> > +Normal comment sections should be before the code block and >> start with /** on its own line and finish with */ on its own line. >> >> Is it a mandatory requirement to have /** on its own line if >> description fits in one line? >> >> /** macro description */ >> #define SOME_MACRO 0 >> >> >> No it is not, you can use the format below - Commenting on the end of a >> line for #defines and struct members is allowed using /**< <text> */ >> > > So according to description both cases below are ok: > > /** > > * macro description > */ > #define SOME_MACRO 0 > > #define SOME_MACRO 0 /**< macro description */ > > It was asking about a third form, which seems to be acceptable for > doxygen, but not mentioned in this patch: > > > /** macro description */ > #define SOME_MACRO 0 >
diff --git a/CONTRIBUTING b/CONTRIBUTING index 08887de..91e2aa9 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -49,6 +49,19 @@ compiler: Please ensure submitted patches are checkpatch clean before submitting them to avoid having them automatically returned for rework. +Documenting the code + +Allow doxygen to use all its default behaviors to identify tagged information but where a doxygen tag must be specified use @ +The first line is by default the brief summary. +The next paragraph is by default the detailed summary +Normal comment sections should be before the code block and start with /** on its own line and finish with */ on its own line. +Commenting on the end of a line for #defines and struct members is allowed using /**< <text> */ +Files should start with a files description using @file +Functions should specify their parameters with @param[in] and @param[out] +Functions return values should all be specified using @return +There should be no doxygen warnings or errors generated. + + [1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle [2] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches [3] refer to README file.
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- CONTRIBUTING | 13 +++++++++++++ 1 file changed, 13 insertions(+)