What Doxygen tag should I use when a function emits a signal?

[SeanM]

I'm trying to document my code using doxygen, and I'm trying to figure out what the correct tag (if any exists) to use.

I've got a member function that is called whenever an internal QTimer's timeout() signal is emitted. When this happens, this class emits a signal of it's own to notify external class that the timeout happened. So here's my current documentation and function:

/**
 * @brief Called when timer times out
 *
 * This function is called when the timer times out.
 * Emits sigTimeout().
 */
void myClass::slotTimeout()
{
    qDebug("Slot timeout, stopping timer");
    mTimer->stop(); // stop timer if it isn't already
    emit sigTimeout();
}

/**
 * @brief Called when timer times out
 *
 * This function is called when the timer times out.
 * Emits sigTimeout().
 */
void myClass::slotTimeout()
{
    qDebug("Slot timeout, stopping timer");
    mTimer->stop(); // stop timer if it isn't already
    emit sigTimeout();
}

To copy to clipboard, switch view to plain text mode 

So I'd like for the generated HTML documentation for this function to have the "sigTimeout()" as a hyperlink that takes the reader back to the signal documentation. Right now it just shows up as plain text.

[d_stranz]

I don't know if there is a Qt signal-specific tag. I'm not a doxygen guru. I usually use the "see also" (sa) tag followed by the name of the signal.

Apparently there are some Qt-specific tags, because you see things like "[signal]" in Qt documentation. Maybe the best way is to find a bit of Qt documentation that looks like what you want, then search the source code to see how it is tagged.

[Infinity]

How is the signal declared (did you really use the uncommon "sig"-prefix)? Prints doxygen any error messages?

Normally doxygen should be able to detect signals proberly. You can document signals itself like you would document pure virtual methods (using "\fn ..."). Does this work?

[d_stranz]

I think the OP is asking how to document the fact that a function emits a signal, not the declaration of the signal itself.

[SeanM]

I think the OP is asking how to document the fact that a function emits a signal, not the declaration of the signal itself.

Correct. Doxygen is properly documenting the signal itself in the section normally reserved for signals. But I'm trying to document a different function of mine that emits the given signal. In that function's documentation, I want the name of the signal to be a link that takes the user back to the documentation of the signal itself.

So:

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();
 
public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();

public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

To copy to clipboard, switch view to plain text mode 

So I want the "sigBar()" text in the documentation for the foo function to be clickable. It seems like there should be some doxygen tag I add on line 13, before sigBar(), that tells doxygen to link that text back. Right now, it's just plain text.

I don't know if there is a Qt signal-specific tag. I'm not a doxygen guru. I usually use the "see also" (sa) tag followed by the name of the signal.

I'll try this and see what happens!

---

Added after 4 minutes:

I think the OP is asking how to document the fact that a function emits a signal, not the declaration of the signal itself.

Correct. Doxygen is properly documenting the signal itself in the section normally reserved for signals. But I'm trying to document a different function of mine that emits the given signal. In that function's documentation, I want the name of the signal to be a link that takes the user back to the documentation of the signal itself.

So:

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();
 
public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();

public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

To copy to clipboard, switch view to plain text mode 

So I want the "sigBar()" text in the documentation for the foo function to be clickable. It seems like there should be some doxygen tag I add on line 13, before sigBar(), that tells doxygen to link that text back. Right now, it's just plain text.

I don't know if there is a Qt signal-specific tag. I'm not a doxygen guru. I usually use the "see also" (sa) tag followed by the name of the signal.

I'll try this and see what happens!

I think the OP is asking how to document the fact that a function emits a signal, not the declaration of the signal itself.

Correct. Doxygen is properly documenting the signal itself in the section normally reserved for signals. But I'm trying to document a different function of mine that emits the given signal. In that function's documentation, I want the name of the signal to be a link that takes the user back to the documentation of the signal itself.

So:

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();
 
public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();

public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

To copy to clipboard, switch view to plain text mode 

So I want the "sigBar()" text in the documentation for the foo function to be clickable. It seems like there should be some doxygen tag I add on line 13, before sigBar(), that tells doxygen to link that text back. Right now, it's just plain text.

I don't know if there is a Qt signal-specific tag. I'm not a doxygen guru. I usually use the "see also" (sa) tag followed by the name of the signal.

I'll try this and see what happens!

I think the OP is asking how to document the fact that a function emits a signal, not the declaration of the signal itself.

Correct. Doxygen is properly documenting the signal itself in the section normally reserved for signals. But I'm trying to document a different function of mine that emits the given signal. In that function's documentation, I want the name of the signal to be a link that takes the user back to the documentation of the signal itself.

So:

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();
 
public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();

public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

To copy to clipboard, switch view to plain text mode 

So I want the "sigBar()" text in the documentation for the foo function to be clickable. It seems like there should be some doxygen tag I add on line 13, before sigBar(), that tells doxygen to link that text back. Right now, it's just plain text.

I don't know if there is a Qt signal-specific tag. I'm not a doxygen guru. I usually use the "see also" (sa) tag followed by the name of the signal.

I'll try this and see what happens!

I think the OP is asking how to document the fact that a function emits a signal, not the declaration of the signal itself.

Correct. Doxygen is properly documenting the signal itself in the section normally reserved for signals. But I'm trying to document a different function of mine that emits the given signal. In that function's documentation, I want the name of the signal to be a link that takes the user back to the documentation of the signal itself.

So:

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();
 
public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

signals:
  /**
     * @brief Bar signal
     *
     * This signal is a useful signal
     */
  void sigBar();

public:
  /**
     * @brief Foo function
     *
     * This function does all sorts of miraculous things.  Oh, and it emits sigBar()
     */
  void foo();

To copy to clipboard, switch view to plain text mode 

So I want the "sigBar()" text in the documentation for the foo function to be clickable. It seems like there should be some doxygen tag I add on line 13, before sigBar(), that tells doxygen to link that text back. Right now, it's just plain text.

I don't know if there is a Qt signal-specific tag. I'm not a doxygen guru. I usually use the "see also" (sa) tag followed by the name of the signal.

I'll try this and see what happens!

---

Added after 18 minutes:

Well, I'm not entirely sure what I did, but now it appears to be working. It's possible that when I tried it before, I may not have actually documented the signal? Right now I just have:

/**
  * @brief Connection timeout signal
  *
  * Emitted whenever the connection timer times out.
  */
void sigTimeout();
 
 
/**
 * @brief Called when timer times out
 *
 * This function is called when the timer times out.
 * Emits sigTimeout().
 */
void myClass::slotTimeout()
{
    qDebug("Slot timeout, stopping timer");
    mTimer->stop(); // stop timer if it isn't already
    emit sigTimeout();
}

/**
  * @brief Connection timeout signal
  *
  * Emitted whenever the connection timer times out.
  */
void sigTimeout();


/**
 * @brief Called when timer times out
 *
 * This function is called when the timer times out.
 * Emits sigTimeout().
 */
void myClass::slotTimeout()
{
    qDebug("Slot timeout, stopping timer");
    mTimer->stop(); // stop timer if it isn't already
    emit sigTimeout();
}

To copy to clipboard, switch view to plain text mode 

And the documentation for slotTimeout() is correctly linking back to the signal sigTimeout(). Sorry for the noise if that was the problem!