[16/36] libcamera: yaml_parser: Drop unneeded \fn Doxygen commands

25736 diff mbox series

There's no need to specify the function name in Doxygen comment blocks
with \fn if the documentation directly precedes the function definition.
Drop the unneeded \fn.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 src/libcamera/yaml_parser.cpp | 7 -------
 1 file changed, 7 deletions(-)

2026. 01. 13. 1:07 keltezéssel, Laurent Pinchart írta:
> There's no need to specify the function name in Doxygen comment blocks
> with \fn if the documentation directly precedes the function definition.
> Drop the unneeded \fn.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---

The whole `YamlParserContext` is not visible to doxygen, no? At least I see
`#ifndef __DOXYGEN__` around it. And even if was, private things are excluded
by doxygen.

Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>


>   src/libcamera/yaml_parser.cpp | 7 -------
>   1 file changed, 7 deletions(-)
> 
> diff --git a/src/libcamera/yaml_parser.cpp b/src/libcamera/yaml_parser.cpp
> index 46c1fb9bce7e..0ef1f3ea303b 100644
> --- a/src/libcamera/yaml_parser.cpp
> +++ b/src/libcamera/yaml_parser.cpp
> @@ -86,7 +86,6 @@ YamlObject::~YamlObject() = default;
>    */
>   
>   /**
> - * \fn YamlObject::size()
>    * \brief Retrieve the number of elements in a dictionary or list YamlObject
>    *
>    * This function retrieves the size of the YamlObject, defined as the number of
> @@ -541,7 +540,6 @@ YamlParserContext::~YamlParserContext()
>   }
>   
>   /**
> - * \fn YamlParserContext::init()
>    * \brief Initialize a parser with an opened file for parsing
>    * \param[in] fh The YAML file to parse
>    *
> @@ -580,7 +578,6 @@ int YamlParserContext::yamlRead(void *data, unsigned char *buffer, size_t size,
>   }
>   
>   /**
> - * \fn YamlParserContext::nextEvent()
>    * \brief Get the next event
>    *
>    * Get the next event in the current YAML event stream, and return nullptr when
> @@ -609,7 +606,6 @@ YamlParserContext::EventPtr YamlParserContext::nextEvent()
>   }
>   
>   /**
> - * \fn YamlParserContext::parseContent()
>    * \brief Parse the content of a YAML document
>    * \param[in] yamlObject The result of YamlObject
>    *
> @@ -648,7 +644,6 @@ int YamlParserContext::parseContent(YamlObject &yamlObject)
>   }
>   
>   /**
> - * \fn YamlParserContext::readValue()
>    * \brief Parse event scalar and fill its content into a string
>    *
>    * A helper function to parse a scalar event as string. The caller needs to
> @@ -663,7 +658,6 @@ std::string YamlParserContext::readValue(EventPtr event)
>   }
>   
>   /**
> - * \fn YamlParserContext::parseDictionaryOrList()
>    * \brief A helper function to abstract the common part of parsing dictionary or list
>    * \param[in] endEventType The YAML end event type (sequence or mapping)
>    * \param[in] parseItem The callback to handle an item
> @@ -707,7 +701,6 @@ int YamlParserContext::parseDictionaryOrList(yaml_event_type_t endEventType,
>   }
>   
>   /**
> - * \fn YamlParserContext::parseNextYamlObject()
>    * \brief Parse next YAML event and read it as a YamlObject
>    * \param[in] yamlObject The result of YamlObject
>    * \param[in] event The leading event of the object

On Tue, Jan 13, 2026 at 05:38:11PM +0100, Barnabás Pőcze wrote:
> 2026. 01. 13. 1:07 keltezéssel, Laurent Pinchart írta:
> > There's no need to specify the function name in Doxygen comment blocks
> > with \fn if the documentation directly precedes the function definition.
> > Drop the unneeded \fn.
> > 
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> 
> The whole `YamlParserContext` is not visible to doxygen, no? At least I see
> `#ifndef __DOXYGEN__` around it. And even if was, private things are excluded
> by doxygen.

You're right. I think it was initially documented for our internal use.
We could drop the documentation, but I think it's still useful.

> Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> 
> >   src/libcamera/yaml_parser.cpp | 7 -------
> >   1 file changed, 7 deletions(-)
> > 
> > diff --git a/src/libcamera/yaml_parser.cpp b/src/libcamera/yaml_parser.cpp
> > index 46c1fb9bce7e..0ef1f3ea303b 100644
> > --- a/src/libcamera/yaml_parser.cpp
> > +++ b/src/libcamera/yaml_parser.cpp
> > @@ -86,7 +86,6 @@ YamlObject::~YamlObject() = default;
> >    */
> >   
> >   /**
> > - * \fn YamlObject::size()
> >    * \brief Retrieve the number of elements in a dictionary or list YamlObject
> >    *
> >    * This function retrieves the size of the YamlObject, defined as the number of
> > @@ -541,7 +540,6 @@ YamlParserContext::~YamlParserContext()
> >   }
> >   
> >   /**
> > - * \fn YamlParserContext::init()
> >    * \brief Initialize a parser with an opened file for parsing
> >    * \param[in] fh The YAML file to parse
> >    *
> > @@ -580,7 +578,6 @@ int YamlParserContext::yamlRead(void *data, unsigned char *buffer, size_t size,
> >   }
> >   
> >   /**
> > - * \fn YamlParserContext::nextEvent()
> >    * \brief Get the next event
> >    *
> >    * Get the next event in the current YAML event stream, and return nullptr when
> > @@ -609,7 +606,6 @@ YamlParserContext::EventPtr YamlParserContext::nextEvent()
> >   }
> >   
> >   /**
> > - * \fn YamlParserContext::parseContent()
> >    * \brief Parse the content of a YAML document
> >    * \param[in] yamlObject The result of YamlObject
> >    *
> > @@ -648,7 +644,6 @@ int YamlParserContext::parseContent(YamlObject &yamlObject)
> >   }
> >   
> >   /**
> > - * \fn YamlParserContext::readValue()
> >    * \brief Parse event scalar and fill its content into a string
> >    *
> >    * A helper function to parse a scalar event as string. The caller needs to
> > @@ -663,7 +658,6 @@ std::string YamlParserContext::readValue(EventPtr event)
> >   }
> >   
> >   /**
> > - * \fn YamlParserContext::parseDictionaryOrList()
> >    * \brief A helper function to abstract the common part of parsing dictionary or list
> >    * \param[in] endEventType The YAML end event type (sequence or mapping)
> >    * \param[in] parseItem The callback to handle an item
> > @@ -707,7 +701,6 @@ int YamlParserContext::parseDictionaryOrList(yaml_event_type_t endEventType,
> >   }
> >   
> >   /**
> > - * \fn YamlParserContext::parseNextYamlObject()
> >    * \brief Parse next YAML event and read it as a YamlObject
> >    * \param[in] yamlObject The result of YamlObject
> >    * \param[in] event The leading event of the object