Skip to content
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.

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

Specify documentation except for listed languages. #10809

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

Conversation

albert-github
Copy link
Collaborator

@albert-github albert-github commented Apr 19, 2024

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.

Example: example.tar.gz

Adjusted example (due to bc508bd) : example1.tar.gz

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.
@albert-github albert-github added the enhancement a request to enhance doxygen, not a bug label Apr 19, 2024
doc/commands.dox Outdated
@@ -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.

Better distinction between "except" usage and "normal usage" du to commands `\~!` and `\~`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement a request to enhance doxygen, not a bug
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants