doxygen/doxygen-check.py

   1 #!/usr/bin/python
   2 #
   3 # This file is part of the GROMACS molecular simulation package.
   4 #
   5 # Copyright (c) 2014, by the GROMACS development team, led by
   6 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7 # and including many others, as listed in the AUTHORS file in the
   8 # top-level source directory and at http://www.gromacs.org.
   9 #
  10 # GROMACS is free software; you can redistribute it and/or
  11 # modify it under the terms of the GNU Lesser General Public License
  12 # as published by the Free Software Foundation; either version 2.1
  13 # of the License, or (at your option) any later version.
  14 #
  15 # GROMACS is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 # Lesser General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU Lesser General Public
  21 # License along with GROMACS; if not, see
  22 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24 #
  25 # If you want to redistribute modifications to GROMACS, please
  26 # consider that scientific software is very special. Version
  27 # control is crucial - bugs must be traceable. We will be happy to
  28 # consider code for inclusion in the official distribution, but
  29 # derived work must not be called official GROMACS. Details are found
  30 # in the README & COPYING files - if they are missing, get the
  31 # official version at http://www.gromacs.org.
  32 #
  33 # To help us fund GROMACS development, we humbly ask that you cite
  34 # the research papers on the package. Check out http://www.gromacs.org.
  35
  36 """Check Doxygen documentation for issues that Doxygen does not warn about.
  37
  38 This script for some issues in the Doxygen documentation, using Doxygen XML
  39 output.  Part of the checks are generic, like checking that all documented
  40 entities have brief descriptions.  Other are specific to GROMACS, like checking
  41 that only installed headers contribute to the public API documentation.
  42
  43 The checks should be self-evident from the source code of the script.
  44 All the logic of parsing the Doxygen XML output and creating a GROMACS-specific
  45 representation of the source tree is separated into separate Python modules
  46 (doxygenxml.py and gmxtree.py, respectively).  Similarly, logic for handling
  47 the output messages is in reporter.py.   This leaves only the actual checks and
  48 the script command-line interface in this file.
  49
  50 The script can be run using the 'doc-check' target generated by CMake.
  51 This target takes care of generating all the necessary input files and passing
  52 them to the script.
  53 """
  54
  55 import sys
  56 from optparse import OptionParser
  57
  58 from gmxtree import GromacsTree, DocType
  59 from reporter import Reporter
  60
  61 def check_file(fileobj, reporter):
  62     """Check file-level documentation."""
  63     if not fileobj.is_documented():
  64         # TODO: Add rules for required documentation
  65         return
  66
  67     if fileobj.is_source_file():
  68         # TODO: Add rule to exclude examples from this check
  69         if fileobj.is_installed():
  70             reporter.file_error(fileobj, "source file is installed")
  71         if fileobj.get_documentation_type() != DocType.internal:
  72             reporter.file_error(fileobj,
  73                     "source file documentation appears outside full documentation")
  74         elif fileobj.get_api_type() != DocType.internal:
  75             reporter.file_error(fileobj, "source file marked as non-internal")
  76     elif fileobj.is_test_file() and fileobj.is_installed():
  77         reporter.file_error(fileobj, "test file is installed")
  78     elif fileobj.is_installed():
  79         if fileobj.get_documentation_type() != DocType.public:
  80             reporter.file_error(fileobj,
  81                     "public header has non-public documentation")
  82     elif fileobj.get_documentation_type() == DocType.public:
  83         reporter.file_error(fileobj,
  84                 "non-installed header has public documentation")
  85     elif fileobj.get_api_type() == DocType.public:
  86         reporter.file_error(fileobj,
  87                 "non-installed header specified as part of public API")
  88     elif fileobj.get_documentation_type() < fileobj.get_api_type():
  89         reporter.file_error(fileobj,
  90                 "API type ({0}) conflicts with documentation visibility ({1})"
  91                 .format(fileobj.get_api_type(), fileobj.get_documentation_type()))
  92
  93     if not fileobj.has_brief_description():
  94         reporter.file_error(fileobj,
  95                 "is documented, but does not have brief description")
  96
  97     expectedmod = fileobj.get_expected_module()
  98     if expectedmod:
  99         docmodules = fileobj.get_doc_modules()
 100         if docmodules:
 101             for module in docmodules:
 102                 if module != expectedmod:
 103                     reporter.file_error(fileobj,
 104                             "is documented in incorrect module: {0}"
 105                             .format(module.get_name()))
 106         elif expectedmod.is_documented():
 107             reporter.file_error(fileobj,
 108                     "is not documented in any module, but {0} exists"
 109                     .format(expectedmod.get_name()))
 110
 111 def check_entity(entity, reporter):
 112     """Check documentation for a code construct."""
 113     if entity.is_documented():
 114         if not entity.has_brief_description():
 115             reporter.doc_error(entity,
 116                     "is documented, but does not have brief description")
 117
 118 def check_class(classobj, reporter):
 119     """Check documentation for a class/struct/union."""
 120     check_entity(classobj, reporter)
 121     if classobj.is_documented():
 122         classtype = classobj.get_documentation_type()
 123         filetype = classobj.get_file_documentation_type()
 124         if classtype == DocType.public and not classobj.is_in_installed_file():
 125             reporter.doc_error(classobj,
 126                     "has public documentation, but is not in installed header")
 127         elif filetype is not DocType.none and classtype > filetype:
 128             reporter.doc_error(classobj,
 129                     "is in {0} file(s), but appears in {1} documentation"
 130                     .format(filetype, classtype))
 131
 132 def check_member(member, reporter):
 133     """Check documentation for a generic member."""
 134     check_entity(member, reporter)
 135     if member.is_documented():
 136         if not member.is_visible():
 137             # TODO: This is triggered by members in anonymous namespaces.
 138             reporter.doc_note(member,
 139                     "is documented, but is ignored by Doxygen, because its scope is not documented")
 140         if member.has_inbody_description():
 141             reporter.doc_note(member, "has in-body comments, which are ignored")
 142
 143 def main():
 144     """Run the checking script."""
 145     parser = OptionParser()
 146     parser.add_option('-S', '--source-root',
 147                       help='Source tree root directory')
 148     parser.add_option('-B', '--build-root',
 149                       help='Build tree root directory')
 150     parser.add_option('--installed',
 151                       help='Read list of installed files from given file')
 152     parser.add_option('-l', '--log',
 153                       help='Write issues into a given log file in addition to stderr')
 154     parser.add_option('--ignore',
 155                       help='Set file with patterns for messages to ignore')
 156     parser.add_option('--check-ignored', action='store_true',
 157                       help='Check documentation ignored by Doxygen')
 158     parser.add_option('-q', '--quiet', action='store_true',
 159                       help='Do not write status messages')
 160     options, args = parser.parse_args()
 161
 162     installedlist = []
 163     if options.installed:
 164         with open(options.installed, 'r') as outfile:
 165             for line in outfile:
 166                 installedlist.append(line.strip())
 167
 168     reporter = Reporter(options.log)
 169     if options.ignore:
 170         reporter.load_filters(options.ignore)
 171
 172     if not options.quiet:
 173         sys.stderr.write('Scanning source tree...\n')
 174     tree = GromacsTree(options.source_root, options.build_root, reporter)
 175     tree.set_installed_file_list(installedlist)
 176     if not options.quiet:
 177         sys.stderr.write('Reading Doxygen XML files...\n')
 178     tree.load_xml()
 179
 180     reporter.write_pending()
 181
 182     if not options.quiet:
 183         sys.stderr.write('Checking...\n')
 184
 185     for fileobj in tree.get_files():
 186         check_file(fileobj, reporter)
 187
 188     for classobj in tree.get_classes():
 189         check_class(classobj, reporter)
 190
 191     for memberobj in tree.get_members():
 192         if memberobj.is_visible() or options.check_ignored:
 193             check_member(memberobj, reporter)
 194
 195     # TODO: Check #include statements, like old 'make doccheck'
 196
 197     reporter.write_pending()
 198     reporter.report_unused_filters()
 199     reporter.close_log()
 200
 201 main()