Snippet in same file to share docs

[zhangzq]

Hi, I need to share docs between functions and params.

As I know, writing the snippet in seperator example file and using @snippetdoc to include the file and snippet will works. But it will be more clear if I can write the snippet in the same file . In most case, I only use the snippet in same file.

Below is a short example. Currently it not works.

# example.py

## @snippet common_param_a
# @param a This is a common parameter that appears in many functions.
## @endsnippet common_param_a

## @brief This is a function.
# @snippetdoc common_param_a
# @param b This is another parameter.
def function1(a, b):
    pass

## @brief This is another function.
# @snippetdoc common_param_a
# @param c This is a different parameter.
def function2(a, c):
    pass

[albert-github]

You wrote:

As I know, writing the snippet in separate example file and using @snippetdoc to include the file and snippet will works. But it will be more clear if I can write the snippet in the same file . In most case, I only use the snippet in same file.

Doxygen can have the code snippets in the same file and address these in the same way as it would do with do with snippets in a separate file, so can you show what you did:

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).
• Please also specify the full doxygen version used (doxygen -v).

Furthermore in your snippet you use the commands \snippet and \endsnippet:

• \snippet is a doxygen command to include a code snippet, not to define a snippet
• \endsnippet where is this command defined?
• I don't see any snippet placeholder [...] in your code

I would have expected that the following would work:

## \file

# [common_param_a]
# @param a This is a common parameter that appears in many functions.
# [common_param_a]

## @brief This is a function.
#
# @snippetdoc example.py common_param_a
# @param b This is another parameter.
def function1(a, b):
    pass

## @brief This is another function.
#
# @snippetdoc example.py common_param_a
# @param c This is a different parameter.
def function2(a, c):
    pass

though this gives (in the current master version (1.11.0 (78422d3)):

example.py:4: warning: '\param' command is not allowed in section title, ending section title.
example.py:4: warning: '\param' command is not allowed in section title, ending section title.

and in the 1.10.0 version:

example.py:9: warning: The following parameter of example.function1(a, b) is not documented:
  parameter 'a'
example.py:16: warning: The following parameter of example.function2(a, c) is not documented:
  parameter 'a'

(Normally one would not use example.py in this case but the placeholder this but this didn't work in 1.10.0 but has been corrected in the mean time).

A workaround is currently:

## \file

""" [common_param_a]
    @param a This is a common parameter that appears in many functions.
    [common_param_a]"""

## @brief This is a function.
# @snippetdoc example.py common_param_a
# @param b This is another parameter.
def function1(a, b):
    pass

## @brief This is another function.
# @snippetdoc example.py common_param_a
# @param c This is a different parameter.
def function2(a, c):
    pass

[zhangzq]

you example works (previously I didn't know this), Thanks!

""" [common_param_a]
    @param a This is a common parameter that appears in many functions.
    [common_param_a]"""

## @brief This is a function.
# @snippetdoc this common_param_a
# @param b This is another parameter.
def function1(a, b):
    pass

[albert-github]

I've just pushed a proposed patch, pull request #10826

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).