Doxygen comments

[David Haslam]

When I submit fixes, is it acceptable to also add new doxygen comments? In particular, I'd like to at least add \brief class descriptions where I've worked out what something does.

Also, is there any preference for the comment style: /**, ///, /*!, //!

--

[Gilles Caulier-4]

Hi and happy new year.

All pull requests are welcome of course, especially brief descriptions
of classes.

Doxygen comment in digiKam use /** ... */

For inline comment, we use ///< ...

Best regards

Gilles Caulier

Le mar. 5 janv. 2021 à 17:43, David Haslam <[hidden email]> a écrit :
>
> When I submit fixes, is it acceptable to also add new doxygen comments? In particular, I'd like to at least add \brief class descriptions where I've worked out what something does.
>
> Also, is there any preference for the comment style: /**, ///, /*!, //!
>
> --
>
> David

[David Haslam]

Thanks, and Happy New Year to all.

On 05/01/2021 16:47, Gilles Caulier wrote:

Hi and happy new year.

All pull requests are welcome of course, especially brief descriptions
of classes.

Doxygen comment in digiKam use /** ... */

For inline comment, we use ///< ...

Best regards

Gilles Caulier

Le mar. 5 janv. 2021 à 17:43, David Haslam [hidden email] a écrit :

When I submit fixes, is it acceptable to also add new doxygen comments? In particular, I'd like to at least add \brief class descriptions where I've worked out what something does.

Also, is there any preference for the comment style: /**, ///, /*!, //!

--

David

[David Haslam]

So I tried adding some new comments and noticed they didn't appear in the doxygen output. In fact I noticed may classes are missing.

After a bit of digging it seems that doxygen doesn't like the Q_DECL_HIDDEN macro. So I've added these lines to Doxyfile

MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = Q_DECL_HIDDEN= \
                         Q_OBJECT=

This strips out these macros from the doxygen preprocessor.

I also added these, as I think the output is useful.

SHOW_USED_FILES        = YES
SHOW_FILES             = YES

And finally I updated the overall config file to a more recent one. A lot of comments changed, so the commit is a bit noisy, sorry.

I hope this is acceptable.

A merge request has been sent, which also includes some minor Mainpage.dox fixes.

Thanks.

On 05/01/2021 16:47, Gilles Caulier wrote:

Hi and happy new year.

All pull requests are welcome of course, especially brief descriptions
of classes.

Doxygen comment in digiKam use /** ... */

For inline comment, we use ///< ...

Best regards

Gilles Caulier

Le mar. 5 janv. 2021 à 17:43, David Haslam [hidden email] a écrit :

When I submit fixes, is it acceptable to also add new doxygen comments? In particular, I'd like to at least add \brief class descriptions where I've worked out what something does.

Also, is there any preference for the comment style: /**, ///, /*!, //!

--

David

[Gilles Caulier-4]

PR is now merged into git/master

Thanks

Gilles Caulier

Le sam. 9 janv. 2021 à 18:51, David Haslam <[hidden email]> a écrit :

>
> So I tried adding some new comments and noticed they didn't appear in the doxygen output. In fact I noticed may classes are missing.
>
> After a bit of digging it seems that doxygen doesn't like the Q_DECL_HIDDEN macro. So I've added these lines to Doxyfile
>
> MACRO_EXPANSION        = YES
> EXPAND_ONLY_PREDEF     = YES
> PREDEFINED             = Q_DECL_HIDDEN= \
>                          Q_OBJECT=
>
> This strips out these macros from the doxygen preprocessor.
>
> I also added these, as I think the output is useful.
>
> SHOW_USED_FILES        = YES
> SHOW_FILES             = YES
>
> And finally I updated the overall config file to a more recent one. A lot of comments changed, so the commit is a bit noisy, sorry.
>
> I hope this is acceptable.
>
> A merge request has been sent, which also includes some minor Mainpage.dox fixes.
>
> Thanks.
>
> --
> David
>
> On 05/01/2021 16:47, Gilles Caulier wrote:
>
> Hi and happy new year.
>
> All pull requests are welcome of course, especially brief descriptions
> of classes.
>
> Doxygen comment in digiKam use /** ... */
>
> For inline comment, we use ///< ...
>
> Best regards
>
> Gilles Caulier
>
> Le mar. 5 janv. 2021 à 17:43, David Haslam <[hidden email]> a écrit :
>
> When I submit fixes, is it acceptable to also add new doxygen comments? In particular, I'd like to at least add \brief class descriptions where I've worked out what something does.
>
> Also, is there any preference for the comment style: /**, ///, /*!, //!
>
> --
>
> David