8000 Specify documentation except for listed languages. by albert-github · Pull Request #10809 · doxygen/doxygen · GitHub
[go: up one dir, main page]
Skip to content

Specify documentation except for listed languages. #10809

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Specify documentation except for listed languages. #10809

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b18e9c2
Specify documentation except for listed languages.
albert-github Apr 19, 2024
bc78f9b
Merge branch 'master' into feature/bug_langcmd_exclude
albert-github Apr 22, 2024
bc508bd
Specify documentation except for listed languages.
albert-github Apr 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Specify documentation except for listed languages. 
With the commands `\~` and `\~LanguageId` it is possible to specify comments for one or all languages.
When one wants to write the documentation for the languages except for some specified this needs a complete set of commands, with this enhancement this can be done with one command.
  • Loading branch information
@albert-github
albert-github committed Apr 19, 2024
commit b18e9c2057e89c4d09aa4b761b643ff42460bfee
8 changes: 5 additions & 3 deletions doc/commands.dox
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4099,18 +4099,20 @@ class Receiver
because doxygen uses it to detect Javadoc commands.

<hr>
\section cmdtilde \\~[LanguageId]
\section cmdtilde \\~[LanguageId] or \\~'{'LanguageId [,LanguageId]*'}'
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have some concerns.

  1. Is there a use-case for this? I can only think about using it as fallback telling some translation is missing.
  2. I think the \~lang and \~{lang} look a bit too similar, and it is not intuitively clear one is the negation of the other, maybe \~!{lang} would be more clear.
  3. From a usability point of view, I would prefer something like \~dutch Nederlands \~german Deutsch \~else Fallback to e.g. english text \~.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. No there is not a direct use case, but it is a bit strange that one cannot easily signal the fallback telling some translation is missing.
  2. They are indeed quite similar, \~!{lang} would indeed be more clear.
  3. I thought about this as well but decided against it as
    • one has to keep track of which language have already been selected and reset the list when \~ is given / end of a comment block
    • the current solution gives also a possibility to have \~dutch Nederlands \~german Deutsch \~{dutch} some "Fallback" even for a previous handled language (probably quite unusual / uncommon but gives more flexibility) \~.

I think best is to implement the solution mentioned under 2.

\addindex \\~
This command enables/disables a language specific filter. This can be
used to put documentation for different language into one comment block
and use the \ref cfg_output_language "OUTPUT_LANGUAGE" tag to filter out only a specific language.
Use \c \\~language_id to enable output for a specific language only and
Use \c \\~language_id to enable output for a specific language only,
\c \\~{LanguageId's} to enable output for all languages except for the ones specified in the options list and
\c \\~ to enable output for all languages (this is also the default mode).

Example:
\verbatim
/*! \~english This is English \~dutch Dit is Nederlands \~german Dies ist
Deutsch. \~ output for all languages.
Deutsch. \~{english, dutch, german} output for all languages but English, Dutch and German
\~ output for all languages.
*/
\endverbatim

Expand Down
78 changes: 67 additions & 11 deletions src/commentscan.l
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1002,6 +1002,34 @@ STopt [^\n@\\]*
BEGIN(SkipLang);
}
}
<Comment>{B}*{CMD}"~{"({B}*[a-zA-Z-]*{B}*,)*{B}*[a-zA-Z-]*{B}*"}" {
QCString fullMatch = QCString(yytext).stripWhiteSpace();
QCString optStr = fullMatch.mid(3,fullMatch.length()-4).stripWhiteSpace();
StringVector optList = split(optStr.str(),",");
bool supportedLang = false;
for (const auto &opt : optList)
{
QCString stripLang = QCString(opt.c_str()).stripWhiteSpace();
if (stripLang.isEmpty())
{
// ignore;
}
else if (Config_isAvailableEnum(OUTPUT_LANGUAGE,stripLang))
{
if (qstricmp(Config_getEnumAsString(OUTPUT_LANGUAGE),stripLang)==0) supportedLang = true;
}
else
{
warn(yyextra->fileName,yyextra->lineNr,
"non supported language '%s' specified in '%s'",
qPrint(opt),QCString(yytext).stripWhiteSpace().data());
}
}
if (supportedLang)
{
BEGIN(SkipLang);
}
}
<Comment>{B}*{CMD}"f{"[^}\n]+"}"("{"?) { // start of a formula with custom environment
setOutput(yyscanner,OutputDoc);
yyextra->formulaText="\\begin";
Expand Down Expand Up @@ -2406,63 +2434,63 @@ STopt [^\n@\\]*
if (*yytext=='\n') yyextra->lineNr++;
addOutput(yyscanner,'\n');
}
<SkipInternal>[@\\]"if"/[ \t] {
<SkipInternal>{CMD}"if"/[ \t] {
yyextra->condCount++;
}
<SkipInternal>[@\\]"ifnot"/[ \t] {
<SkipInternal>{CMD}"ifnot"/[ \t] {
yyextra->condCount++;
}
<SkipInternal>[@\\]/"endif" {
<SkipInternal>{CMD}/"endif" {
yyextra->condCount--;
if (yyextra->condCount<0) // handle conditional section around of \internal, see bug607743
{
unput('\\');
BEGIN(Comment);
}
}
<SkipInternal>[@\\]/"section"[ \t] {
<SkipInternal>{CMD}/"section"[ \t] {
if (yyextra->sectionLevel>0)
{
unput('\\');
BEGIN(Comment);
}
}
<SkipInternal>[@\\]/"subsection"[ \t] {
<SkipInternal>{CMD}/"subsection"[ \t] {
if (yyextra->sectionLevel>1)
{
unput('\\');
BEGIN(Comment);
}
}
<SkipInternal>[@\\]/"subsubsection"[ \t] {
<SkipInternal>{CMD}/"subsubsection"[ \t] {
if (yyextra->sectionLevel>2)
{
unput('\\');
BEGIN(Comment);
}
}
<SkipInternal>[@\\]/"paragraph"[ \t] {
<SkipInternal>{CMD}/"paragraph"[ \t] {
if (yyextra->sectionLevel>3)
{
unput('\\');
BEGIN(Comment);
}
}
<SkipInternal>[@\\]/"subparagraph"[ \t] {
<SkipInternal>{CMD}/"subparagraph"[ \t] {
if (yyextra->sectionLevel>4)
{
unput('\\');
BEGIN(Comment);
}
}
<SkipInternal>[@\\]/"subsubparagraph"[ \t] {
<SkipInternal>{CMD}/"subsubparagraph"[ \t] {
if (yyextra->sectionLevel>5)
{
unput('\\');
BEGIN(Comment);
}
}
<SkipInternal>[@\\]"endinternal"[ \t]* {
<SkipInternal>{CMD}"endinternal"[ \t]* {
BEGIN(Comment);
}
<SkipInternal>[^ \\@\n]+ { // skip non-special characters
Expand Down Expand Up @@ -2659,7 +2687,7 @@ STopt [^\n@\\]*

/* ----- handle language specific sections ------- */

<SkipLang>[\\@]"~"[a-zA-Z-]* { /* language switch */
<SkipLang>{CMD}"~"[a-zA-Z-]* { /* language switch */
QCString langId(&yytext[2]);
if (!langId.isEmpty() && !Config_isAvailableEnum(OUTPUT_LANGUAGE,langId))
{
Expand All @@ -2672,6 +2700,34 @@ STopt [^\n@\\]*
BEGIN(Comment);
}
}
<SkipLang>{CMD}"~{"({B}*[a-zA-Z-]*{B}*,)*{B}*[a-zA-Z-]*{B}*"}" { /* language switch */
QCString fullMatch = QCString(yytext);
QCString optStr = fullMatch.mid(3,fullMatch.length()-4).stripWhiteSpace();
StringVector optList = split(optStr.str(),",");
bool supportedLang = false;
for (const auto &opt : optList)
{
QCString stripLang = QCString(opt.c_str()).stripWhiteSpace();
if (stripLang.isEmpty())
{
// ignore;
}
else if (Config_isAvailableEnum(OUTPUT_LANGUAGE,stripLang))
{
if (qstricmp(Config_getEnumAsString(OUTPUT_LANGUAGE),stripLang)==0) supportedLang = true;
}
else
{
warn(yyextra->fileName,yyextra->lineNr,
"non supported language '%s' specified in '%s'",
qPrint(opt),QCString(yytext).stripWhiteSpace().data());
}
}
if (!supportedLang)
{
BEGIN(Comment);
}
}
<SkipLang>[^*@\\\n]* { /* any character not a *, @, backslash or new line */
}
<SkipLang>{DOCNL} { /* new line in verbatim block */
Expand Down
0