Support //! and \param comments

[KUGA2]

Our doxygen style is:

1. CPP comment style
2. doxygen marker: ! -> //!
3. keywords with \ not with @
4. Empty last line (when doxygen commit is more then 1 line): //!
5. Same for c, cpp, h, hpp ... files
6. no \brief (aka AUTOBRIEF)

Example:

//! Creates a thread.
//!
//! This function creates a thread.
//!
//! \note Consult \ref C_Threads_Priorities for choosing an appropriate priority
//!       for your thread.
//!
//! \param[out] thread       Pointer to a thread_t variable. Will contain the thread handle after creation.
//! \param[in] name          Name of the thread to create
//! \param[in] priority      The Priority of the thread
//! \param[in] stackSize     The requested Stacksize
//! \param[in] entryPt       Ptr to the function to execute
//! \param[in] arg           argument given to the thread function
//! \param[in] joinable      if the thread should be joinable or not
//!
//! \retval #OK
//! \retval #ERR_ILLEGAL_OP
//! \retval #ERR_INVALID_ARG
//! \retval #ERR_OBJECT_NOT_FOUND  Unsupported priority
//! \retval #ERR_INTERNAL
//!
STATUS thread_create(thread_t* thread, const char *name, int priority,
                                    int stackSize, THREADFUNCPTR entryPt, void *arg, BOOL joinable);

I looked at all configuration options, and I think this is currently not possible. Am I right?

1. You have examples with ///, but I do not know how i can trigger them myself.
2. not configurable?
3. not configurable?
4. not configurable?
5. thats probably default?
6. can be done with: doxdocgen.generic.briefTemplate

[cschlosser]

Hi @KUGA2 ,

Please try with these configuration settings:

"doxdocgen.generic.order": [
    "empty",
    "tparam",
    "param",
    "empty",
    "return"
  ],
"doxdocgen.generic.paramTemplate": "\param {param} ",
"doxdocgen.generic.returnTemplate": "\retval ",
"doxdocgen.c.commentPrefix": "//! ",
"doxdocgen.c.firstLine": "//!",
"doxdocgen.c.lastLine": "//!",

This should deal with 2.-6 for your Doxygen style.

You have examples with ///, but I do not know how i can trigger them myself.

The trigger sequence can be configured with this setting:

"doxdocgen.c.triggerSequence": "/**",

set it to whatever you want, e.g. the default or the suggested /// or //! if you're more comfortable with that.

Please get back to me if this resolved (some) of your question(s). If you're still unsure or something doesn't work please reply here.

[KUGA2]

Thank you for this nice response.

First of all, I need to to double slash the configs "doxdocgen.generic.paramTemplate": "\\param {param} ",. Easy fix :) Is still got a few issues. The result is:

//!
//! <cursor>
//! \param thread
//! \param name
//! \param priority
//! \param stackSize
//! \param entryPt
//! \param arg
//! \param joinable
//!
//! \retval
//!
STATUS thread_create(thread_t* thread, const char *name, int priority,
                                    int stackSize, THREADFUNCPTR entryPt, void *arg, BOOL joinable);

I think my colleges will be disturbed by the fact, that the cursor is in the line which is supposed to be empty.

Also, I think it would be great do have blank texts. Are there templates for brief and description? (Bonus feature: indention at X spaces!):

//! <brief description><cursor>
//! 
//! <detailed description>
//! 
//! \param thread <parameter description>
//! \param name <parameter description>
//! \param priority <parameter description>
//! \param stackSize <parameter description>
//! \param entryPt <parameter description>
//! \param arg <parameter description>
//! \param joinable <parameter description>
//!
//! \return <return value. use '\retval value description' for specific return values, e.g. with enums>
//!
STATUS thread_create(thread_t* thread, const char *name, int priority,
                                    int stackSize, THREADFUNCPTR entryPt, void *arg, BOOL joinable);

[cschlosser]

Hi @KUGA2 ,

Are there templates for brief and description?

Yes and no. There is a template for brief (and it's default value):

"doxdocgen.generic.briefTemplate": "@brief {text}"

There is no template for the description, yet.

But you could do something like this:

"doxdocgen.c.firstLine": "",
"doxdocgen.generic.order": [
    "brief",
    "empty",
    "custom",
    "empty",
    "tparam",
    "param",
    "empty",
    "return"
  ],
"doxdocgen.generic.customTags": ["<description>"],

I think my colleges will be disturbed by the fact, that the cursor is in the line which is supposed to be empty.

this may also deal with this request.

Bonus feature: indention at X spaces!):

Indentation/alignment is possible.

It looks like this: https://github.com/cschlosser/doxdocgen/blob/master/images/alignment.gif

The full reference how you can configure it can be found here: https://github.com/cschlosser/doxdocgen/blob/master/CHANGELOG.md#alignment

[KUGA2]

Thanks. This works so far. However, on other C(++) elements, there are now a lot of empty lines. Also, the brief collides with the c/dtor texts:

[cschlosser]

Hi @KUGA2 ,

Also, the brief collides with the c/dtor texts:

If you want to disable these texts you can set "doxdocgen.generic.generateSmartText": false.

However, on other C(++) elements, there are now a lot of empty lines.

Was this not the case before? Could you please provide a before/after example if this is new.

[KUGA2]

I actually like the c/dtor texts. But they should overwrite the brief template.

On the empty lines: This is my config now. It works great for functions and methods (as discussed above):

"doxdocgen.generic.briefTemplate": "<brief description>{text}",
"doxdocgen.generic.customTags": ["<detailed description>"],
"doxdocgen.generic.paramTemplate": "\\param[<in/out>] {param}{indent:32}<parameter description>",
"doxdocgen.generic.returnTemplate": "\\retval <value>{indent:32}<value description. Use \\return <descripton> when there are no specific values>",
"doxdocgen.c.commentPrefix": "//! ",
"doxdocgen.c.lastLine": "//!",
"doxdocgen.c.firstLine": "",
"doxdocgen.c.triggerSequence": "//!",
"doxdocgen.generic.order": [
    "brief",
    "empty",
    "custom",
    "empty",
    "tparam",
    "param",
    "empty",
    "return"
  ],

On all other elements, it does not work great:

I guess, this is from the "empty" lines in doxdocgen.generic.order. Removing doxdocgen.generic.order (or the empty lines) make it look ok:

They should only be there, when there is the following chapter. I propose the following setting:

"doxdocgen.generic.emptyLineBeforeChapter" = ["details", "custom", "tparam", "param", "return"] // or "none" / "all"
 "doxdocgen.generic.emptyLineAfterChapter" = ["return"] // or "none" / "all"

[KUGA2]

There is also an issue with the file comments and my settings:

"doxdocgen.generic.briefTemplate": "<brief description>{text}",
"doxdocgen.generic.customTags": ["<detailed description>"],
"doxdocgen.generic.paramTemplate": "\\param[<in/out>] {param}{indent:32}<parameter description>",
"doxdocgen.generic.returnTemplate": "\\retval <value>{indent:32}<value description. Use \\return <descripton> when there are no specific values>",
"doxdocgen.c.commentPrefix": "//! ",
"doxdocgen.c.lastLine": "",
"doxdocgen.c.firstLine": "",
"doxdocgen.c.triggerSequence": "//!",
"doxdocgen.generic.order": [
    "brief",
    "empty",
    "custom",
    "empty",
    "tparam",
    "param",
    "empty",
    "return",
    "empty",
  ],
  // The order to use for the file comment. Values can be used multiple times. Valid values are shown in default setting.
"doxdocgen.file.fileTemplate": "\\file",
"doxdocgen.file.fileOrder": [
    "file",
    "brief",
    "empty",
    "custom"
],

This Results in:

The custom (aka detailed) line is missing.