Closed MarkCallow closed 1 month ago
I should add a caveat to my "new in 1.11.0." I have not used 1.10. so there is a possibility the regression was introduced there. It works in 1.9.7.
Initially this was reported as part of the closed #10517 where already some investigations were done (looks like \snippet{doc}
is not translated in commentcnv)
The problem is in the file ktx/command_create.cpp
around line 63 with the block:
<dd>Encode the texture with the specified codec before saving it.
This option matches the functionality of the ktx_encode "ktx encode" command.
With each choice, the specific and common encoder options listed
@ref ktx_create_options_encoding "below" become valid, otherwise they
are ignored. Case-insensitive.
@snippet{doc} ktx/encode_utils_basis.h command options_basis_encoders
<dt>\--1d</dt>
where the line:
@snippet{doc} ktx/encode_utils_basis.h command options_basis_encoders
runs into the rule (in commentcnv.l around line 1060):
<CComment,ReadLine,IncludeFile>{B}{B}{B}{B}[\\@]("snippet"{OPTS}|"snippetdoc"{OPTS}*) { // Markdown code section
@doxygen probably some initial space counting should have been done, do you see a solution?
@MarkCallow In a number of section labels I see \_
I don´t think the \
should be there.
In a number of section labels I see
\_
I don´t think the\
should be there.
I added them to stop Xcode's Doxygen comment formatting rendering parts of the labels in italics which is due to the _
being taken as italics markers. Adding them didn't seem to cause any problems. They do cause problems in some places, e.g. breaking automatic links, but in many others no problem, including text following @ref
.
If you have another suggestion for stopping Xcode mangling the rendering of names with _
in them, I'm all ears.
@snippet{doc} ktx/encode_utils_basis.h command options_basis_encoders
This line has been this way for a long time and always worked until now. We have many similar @snippet
s in the file I shared and in other files.
\snippet
The handling of the snippets has been changed so it is handled at a better place and more consistent but apparently the handling of the spaces has not been corrected there hence my comment with reference to @doxygen and marking the problem as a bug.\
I saw the problem during running a test with MARDOWN_SUPPORT=NO
. Im not a XCode user so I don
t know what the problem might be there but it is always good to be a bit conservative in using special characters, so it might be better to use "camelCase" instead of things with underscores.handling of the spaces
Which spaces? I tried adding spaces at the start of the @snippet
line in the simple example you made for me, when I started the discussion in #10517, and it still worked.
I saw the problem during running a test with MARDOWN_SUPPORT=NO
Ah! We leave it set to the default, YES, as we have several markdown documents in the project.
Im not a XCode user so I dont know what the problem might be there
The Xcode editor recognizes Doxygen comments and renders them differently in its display. It uses a proportional font, instead of the usual fixed, and recognizes most doxgen commands and renders them appropriately. Here is an example where I have not used any \
.:
That it treats _
s like markdown's and switches to italic looks like an Xcode bug. I'll have to try to find a different workaround.
it might be better to use "camelCase"
That ship has sailed. Since it's a public API I can't easily change it.
It looks like the commit 38ee114 for the issue #10935 and especially the discussion https://github.com/doxygen/doxygen/issues/10935#issuecomment-2184978107 fixes also the issue reported here.
please don't close the issue as this will be done at the moment of an official release.
This issue was previously marked 'fixed but not released', which means it should be fixed in doxygen version 1.12.0. Please verify if this is indeed the case. Reopen the issue if you think it is not fixed and please include any additional information that you think can be relevant (preferably in the form of a self-contained example).
Describe the bug All the @snippet{doc} commands in my doc result in empty code blocks.
Screenshots
To Reproduce Use missing-snippets.tar.gz.
This project has many snippets and all are missing.
Expected behavior Text from all the snippets should be included in the output document.
Version Doxygen v1.11.0 on macOS Sonoma installed from DMG downloaded from doxygen.nl.
Stack trace n/a
Additional context A simple example does not exhibit the problem.