View Issue Details
ID | Project | Category | View Status | Date Submitted | Last Update |
---|---|---|---|---|---|
0001016 | OpenFOAM | Bug | public | 2013-09-13 22:38 | 2015-02-09 19:01 |
Reporter | wyldckat | Assigned To | henry | ||
Priority | low | Severity | trivial | Reproducibility | sometimes |
Status | resolved | Resolution | fixed | ||
Summary | 0001016: bin/tools/doxyFilter fails to retrieve the directory path properly with dash | ||||
Description | The Doxygen generated code documentation doesn't provide the correct paths to the raw source code files when "dash" is used as the default "sh" shell. For example, the current code documentation (for OpenFOAM 2.2.1) at SF.net was possibly generated in Ubuntu ( https://wiki.ubuntu.com/DashAsBinSh ), because it also suffers from this issue with the broken paths to files, as exemplified on this page: http://foam.sourceforge.net/docs/cpp/a00434.html#details As you can see on that page, the following files: DimensionedFieldI.H DimensionedField.C DimensionedFieldIO.C are referencing to the directory "src/OpenFOAM/fields/DimensionedFields/DimensionedField/DimensionedField.H/", which is clearly incorrect, since the header file is not a directory. The reason for this is because "dash" is not able to handle the following line of code properly in the script "bin/tools/doxyFilter": dirName=${filePath%/[^/]*} This is because the expansion of "[^/]" doesn't work on "dash", only on "bash". Possible solutions: 1- Now, I don't know which corner cases the previous line of code was created for, but the following code should work as intended: dirName=${filePath%/*} 2- The other solution is to simply replace in the first line of the script to use "/bin/bash" instead of "/bin/sh". A quick grep in a clean git clone indicates that very few scripts use bash as the default shell interpreter for the script, so I don't know which solution you prefer, but my guess is that performance and portability are the main reasons for this choice. | ||||
Steps To Reproduce | Start a "dash" shell and simulate what the script is meant to do. For example, the attached file "simulated_test.log" is the output of a simulated test for this particular example, with both bash and dash on Ubuntu 12.04. | ||||
Additional Information | After looking at this script, I believe that a small modification to it and to "doc/Doxygen/Allwmake" would allow the generation of the online version of the code documentation to point to the source code on Github, therefore not leaving broken links to the source code files, such as this link: http://foam.sourceforge.net/src/OpenFOAM/fields/DimensionedFields/DimensionedField/DimensionedField.H | ||||
Tags | No tags attached. | ||||
|
simulated_test.log (541 bytes)
user@machine:~/OpenFOAM/OpenFOAM-2.2.x/bin/tools$ filePath=../../../src/OpenFOAM/fields/DimensionedFields/DimensionedField/DimensionedField.H user@machine:~/OpenFOAM/OpenFOAM-2.2.x/bin/tools$ echo ${filePath%/[^/]*} ../../../src/OpenFOAM/fields/DimensionedFields/DimensionedField user@machine:~/OpenFOAM/OpenFOAM-2.2.x/bin/tools$ dash $ filePath=../../../src/OpenFOAM/fields/DimensionedFields/DimensionedField/DimensionedField.H $ echo ${filePath%/[^/]*} ../../../src/OpenFOAM/fields/DimensionedFields/DimensionedField/DimensionedField.H |
|
Attached are the following files: - "bin/tools/doxyFilter" - actually, the file "doxyFilter" is attached, and it only has two changes: using "bash" instead of "sh" and has a few minor updates to the header. It's derived from the latest one on OpenFOAM-dev. - "a00519.html" - it's from an older Doxygen code documentation compilation for OpenFOAM-dev that I had from some other past tests. The detail that can be seen is the same that can currently be seen for the code documentation compilation OpenFOAM 2.3.1 here: http://foam.sourceforge.net/docs/cpp/a00514.html#details - and is the one reported on this bug report. Namely that it's erroneously providing the link to ".../DimensionedField/DimensionedField.H/DimensionedFieldI.H", instead of "".../DimensionedField/DimensionedFieldI.H"" - "a00520.html" - this is the result of using the attached "doxyFilter" script with the latest "OpenFOAM-dev", but with the commit cb23867daa2b6 reverted, due to a glitch that is introduced with the change made on that commit. In all of the 3 pages, use the "#details" anchor at the end of the URL, in order to jump directly to the problem section, namely: Detailed Description template<class Type, class GeoMesh> class Foam::DimensionedField< Type, GeoMesh > Field with dimensions and associated with geometry type GeoMesh which is used to size the field and a reference to it is maintained. Source files DimensionedField.H DimensionedFieldI.H DimensionedField.C DimensionedFieldIO.C The last 3 lines (links) quoted here are the ones that are broken up. As soon as I can I'll report the bug regarding the commit cb23867daa2b6, as well as a feature contribution for adapting the current file paths on the Doxygen documentation to the URLs to the Github repository. |
|
doxyFilter (2,534 bytes)
#!/bin/bash #------------------------------------------------------------------------------ # ========= | # \\ / F ield | OpenFOAM: The Open Source CFD Toolbox # \\ / O peration | # \\ / A nd | Copyright (C) 2011-2015 OpenFOAM Foundation # \\/ M anipulation | #------------------------------------------------------------------------------ # License # This file is part of OpenFOAM. # # OpenFOAM is free software: you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # OpenFOAM is distributed in the hope that it will be useful, but WITHOUT # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License # for more details. # # You should have received a copy of the GNU General Public License # along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>. # # Script # doxyFilter # # Description # pass-through filter for doxygen # # Special treatment for applications/{solvers,utilities}/*.C # - only keep the first comment block of the C source file # use @cond / @endcond to suppress documenting all classes/variables # # Special treatment for applications/{solvers,utilities}/*.H # - use @cond / @endcond to suppress documenting all classes/variables #------------------------------------------------------------------------------ if [ "$#" -gt 0 ] then filePath=$(echo $1 | sed -e s@^$WM_PROJECT_DIR@../../..@ ) # dirName=$(echo "$filePath" | sed -e 's@/[^/]*$@@' ) dirName=${filePath%/[^/]*} fileName=${filePath##*/} awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter.awk case "$1" in */applications/solvers/*.C | */applications/utilities/*.C ) awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter-top.awk ;; # */applications/solvers/*.H | */applications/utilities/*.H ) # awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter-ignore.awk # ;; esac awk -f $WM_PROJECT_DIR/bin/tools/doxyFilter-table.awk $1 | \ awk -f $awkScript | \ sed -f $WM_PROJECT_DIR/bin/tools/doxyFilter.sed \ -e s@%filePath%@$filePath@g \ -e s@%fileName%@$fileName@g \ -e s@%dirName%@$dirName@g fi #------------------------------------------------------------------------------ |
|
|
|
|
|
Resolved by commit 24f0273b9231066f40ddce3f8036104c26dd7c03 in OpenFOAM-2.3.x Resolved by commit ae4cdef8b5a25d898ae60d2fc4c145f08f1af0a1 in OpenFOAM-dev |
Date Modified | Username | Field | Change |
---|---|---|---|
2013-09-13 22:38 | wyldckat | New Issue | |
2013-09-13 22:38 | wyldckat | File Added: simulated_test.log | |
2015-02-07 21:07 | wyldckat | Note Added: 0003717 | |
2015-02-07 21:07 | wyldckat | File Added: doxyFilter | |
2015-02-07 21:08 | wyldckat | File Added: a00519.html | |
2015-02-07 21:08 | wyldckat | File Added: a00520.html | |
2015-02-09 19:01 | henry | Note Added: 0003741 | |
2015-02-09 19:01 | henry | Status | new => resolved |
2015-02-09 19:01 | henry | Resolution | open => fixed |
2015-02-09 19:01 | henry | Assigned To | => henry |