View Issue Details

IDProjectCategoryView StatusLast Update
0001016OpenFOAM[All Projects] Bugpublic2015-02-09 19:01
ReporterwyldckatAssigned Tohenry 
PrioritylowSeveritytrivialReproducibilitysometimes
Status resolvedResolutionfixed 
Product Version 
Fixed in Version 
Summary0001016: bin/tools/doxyFilter fails to retrieve the directory path properly with dash
DescriptionThe 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 ReproduceStart 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 InformationAfter 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
TagsNo tags attached.

Activities

wyldckat

2013-09-13 22:38

updater  

simulated_test.log (541 bytes)

wyldckat

2015-02-07 21:07

updater   ~0003717

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.

wyldckat

2015-02-07 21:07

updater  

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
#------------------------------------------------------------------------------
doxyFilter (2,534 bytes)

wyldckat

2015-02-07 21:08

updater  

a00519.html (322,672 bytes)

wyldckat

2015-02-07 21:08

updater  

a00520.html (322,615 bytes)

henry

2015-02-09 19:01

manager   ~0003741

Resolved by commit 24f0273b9231066f40ddce3f8036104c26dd7c03 in OpenFOAM-2.3.x
Resolved by commit ae4cdef8b5a25d898ae60d2fc4c145f08f1af0a1 in OpenFOAM-dev

Issue History

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