Skip to content

Commit

Permalink
issue doxygen#10820 Snippet in same file to share docs
Browse files Browse the repository at this point in the history
When having e.g.:
```
## \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
```
or analogous in Fortran:
```
!> \file

! [ftn_common_param_a]
!  @param a This is a common parameter that appears in many functions.
! [ftn_common_param_a]

!> @brief This is a function.
!>
!> @snippetdoc this ftn_common_param_a
!> @param b This is another parameter.
subroutine ftn_function1(a, b)
    INTEGER a
    INTEGER b
end subroutine
```
we get warnings like:
```
example.py:4: warning: '\param' command is not allowed in section title, ending section title.
```
and in Fortran the `!` appears in the output

Whilst in C++ the analogous example:
```
/// \file

/** @brief This is a function.
 *  @snippet{doc} this cpp2_common_param_a
 *  @param b This is another parameter. */
void cpp2_function1(int a, int b){}

/*  [cpp2_common_param_a]
 *  @param a This is a common parameter that appears in many functions.
 *  [cpp2_common_param_a]
*/
```
works OK, due to the rule
```
<DocBlock>"\\ilinebr "{B}*"*"/[^/]      {
                                          QCString indent;
                                          indent.fill(' ',computeIndent(yytext+8,yyextra->column));
                                          yyextra->docBlock << "\\ilinebr " << indent;
                                        }
```
added analogous rules for python and Fortran.
  • Loading branch information
albert-github committed Apr 25, 2024
1 parent 78422d3 commit 52c7546
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 0 deletions.
7 changes: 7 additions & 0 deletions src/fortranscanner.l
Original file line number Diff line number Diff line change
Expand Up @@ -1521,6 +1521,13 @@ private {
yyextra->blockLineNr=yyextra->lineNr;
BEGIN(DocCopyBlock);
}
<DocBlock>"\\ilinebr "{B}*"!" {
QCString indent;
indent.fill(' ',yyleng-9);
yyextra->docBlock += "\\ilinebr ";
yyextra->docBlock += indent;
}

<DocBlock>[^@*`~\/\\\n]+ { // any character that isn't special
yyextra->docBlock += yytext;
}
Expand Down
6 changes: 6 additions & 0 deletions src/pyscanner.l
Original file line number Diff line number Diff line change
Expand Up @@ -1507,6 +1507,12 @@ ID [a-z_A-Z%]+{IDSYM}*
({CMD}{CMD}){ID}/[^a-z_A-Z0-9] { // escaped command
yyextra->docBlock+=yytext;
}
"\\ilinebr "{B}*"#" {
QCString indent;
indent.fill(' ',yyleng-9);
yyextra->docBlock += "\\ilinebr ";
yyextra->docBlock += indent;
}
[^#\\@\n]+ { // any other stuff
yyextra->docBlock+=yytext;
}
Expand Down

0 comments on commit 52c7546

Please sign in to comment.