Doxygen has a \file command, I had a look at different code bases and it seems some projects use it, some don't.
Having to maintain this adds some overhead (needs to be corrected when splitting files up) sometimes developers forget to do it.
Is there a way to infer this, eg: use the first doxygen formatted comment in the file as the \file comment.
Otherwise what is a good rule of thumb for when to use \file or not?
Note, I tried removing this command from all files and the output changed to group information less usefully and the order of some information changed, so it does make a difference.
Related
I'm in a situation where I'm programmatically generating LaTeX code, and I want my Synctex to point to the correct lines in the original file.
The generation is basically doing template expansion, so the original files are nearly identical to the generated ones, but with some snippets expanded.
I'm wondering, is there a diff tool or library that will easily give me the line number of the original file that corresponds to a given line in the generated one? Can this be extracted from a normal Unix diff somehow?
This is part of a build script, so ideally something easy to run, like bash or python, is preferred to something that needs to be compiled.
Google’s diff-match-patch lib is a neat solution to questions like these: https://github.com/google/diff-match-patch
I am trying to separate out internal and external documentation using the doxygen constructs of cond; but i just cant seem to get get it working. I would essentially like to exclude some files completely and not conditionally. Regardless of where i add the tag (before include, before header guards etc) , the files and source both show up.
What i have tried in vain is to take the test file from doxegen repo for
conditional test and add it to the project.
Steps to reproduce [Linux]
create a new directory.
copy paste the above file (had to rename it to .h as .c was passed over?).
generate dummy config via doxygen -g.
update Doxyfile ENABLED_SECTION = COND_ENABLED.
Run doxygen.
check html/index.html
This however is still visible in the html documentation it generates for the project. I have set the ENABLED_SECTION variable with other values , but cond_enabled function still shows up. Running the testing directory of the project (doxygen) it passes. So i am lost.
Any suggestions?
Tried with latest version 1.8.14.
Thanks!
Regarding the \cond problems (not an answer directly to the real problem you face, I think, but to long for a comment).
The mentioned file is used in the, limited, testing doxygen can do / does and the first lines contain some instructions on what to do. Furthermore there is a default Doxyfile with the tests in use. It is hard to run a separate test outside the doxygen build tree.
Regarding the remark "Running the testing directory of the project (doxygen) it passes." This is correct, here, at the moment, only testing is done against the XML output and the generated output is compared to a once created version of the XML output. No tests are done, at the moment, in respect to HTML or PDF / LaTeX. Recently the test framework has been slightly extended so in the future this should be possible (compare the xhtml and tex output, but some work has still to be done here).
The version of the parser sees the \cond in the first line (normal C comment) as a doxygen command and skips everything till the first \endcond (your friend in these cases is always doxygen -d preprocessor). I think that removing / modifying the first line will result in an already better result. There is however another hiccup for e.g. HTML output. As the function cond_enabled is not documented and EXPAND_ALL is not set to YES the function will not appear in the documentation. So best is also to add a line of documentation with the function cond_enabled.
Regarding the seen HTML problems I modified the the relevant test in doxygen slightly and pushed a proposed patch to github (pull request 714, https://github.com/doxygen/doxygen/pull/714).
Note: the problem of skipping the \cond in normal C comment is quite a bit harder to implement (seen the logical complexity of the doxygen code in pre.l and commentcnv.l.
EDIT: 2018/06/10: The push request has been integrated in the master version on github.
I just discovered some mentions of how nautilus used to read files named .hidden and hide files matching the patterns listed in them, and at some point that feature was moved to GIO g_file_info_get_is_hidden. However, I haven't been able to get it to work. If I put the exact name of a file into .hidden, it does get hidden, but I'd really like to be able to use a pattern. I can't find any solid or recent documentation about how this feature is supposed to work.
I'd particularly like to hide files matching hg-checkexec-*. Mercurial running under Emacs periodically creates bunches of these temporary files and they gum up my nautilus view.
Is this feature documented anywhere? How is it supposed to work?
Looking at the code, .hidden files as implemented in GIO support one filename per line, with no support for patterns. A .hidden file cannot list files in subdirectories — only those in the same directory.
I don’t know of any documentation about the feature. Please file a bug about adding it.
As a complement to Philip Withnall's answer, I've dived further into the source code, specifically the functions read_hidden_file() and file_is_hidden():
read_hidden_file() basically parses the .hidden in a directory and stores each line in as a key in a GLib HashTable object.
The object is created using g_hash_table_new_full() with parameters g_str_hash, g_str_equal, g_free, NULL. This mean keys are plain strings with comparison being a plain (case-sensitive) string equality, so no globs, regex or any patterns support.
It is populated using g_hash_table_add(), so not used as a key/value pair table but rather as a plain set, with keys being the elements themselves.
file_is_hidden() is called for each content (file or sub-directory) in a given directory. It uses g_hash_table_contains() to check if the file's basename is a key in above object, so no pattern search whatsoever.
So, as Phillip concluded, it seems there is indeed no support for any kind of globs, regexes or pattern seach in .hidden files. I would also die for a .gitignore-like syntax.
Doxygen can generate graphs showing which files in a project include which others, as a directed graph. This is a nice tool, but it only comes in two flavors, namely showing all the files that include (directly or indirectly) a given file, or all the files that are included (again directly or indirectly) by a given file.
I would like to generate a global include graph, containing all the files that Doxygen knows about, and showing the include structure. Is that possible?
One trick that kind of works but feels extremely dirty: add some dummy.h header somewhere, and include it from every other file, or alternatively (a bit cleaner since it doesn't need to touch the other files) have dummy.h manually include everything else. And then manually remove useless includes (which are implied by others as indirect dependencies). That is not the right way to do it...
I need to refer to Doxygen documentation pages. The file names however are not stable as they change after every generation. My idea is to create a symlink to each HTML file created by Doxygen , having a stable and human friendly name. Have anyone tried this?
Actually, it might be very easy just to parse the annotated.html file Doxygen produces. Any documented class shows up there as a line like:
`<tr><td class="indexkey"><a class="el" href="dd/de6/a00548.html">
ImportantClass</a></td>`
The hard problem for me is that I would like to have my file names (i.e. the symlinks) be visible on my server like:
http://www.package.com/com.package.my.ImportantClass.html
[Yes, the code is in java]. So the question actually reads: "how to connect a HTML page by Doxygen with the right java class name and its package name.
You seem to have SHORT_NAMES enabled, which will indeed produce volatile names. When you set SHORT_NAMES to NO in the configuration file (the default), you will get longer names, but these are stable over multiple runs (i.e. they are based on the name, and for functions also on (a hash of) the parameters.