wiki:EaIngestNeeds
Last modified 11 years ago Last modified on 01/23/2008 09:52:58 AM

Working around Problems in EA Reverse Engineering

from: Software Standards and Policies .

LSST C++ Documentation Standards change to accommodate EA

Due to limitations with EA's reverse engineering comment parsing, new constraints are being imposed in the LSST Documentation Standard.

Restated C++ Documentation Standard Rules

Required

  • do not use multi-line inline comments on method parameters
  • use only '@' to precede doxygen special commands (e.g. @params)

Strongly Preferred

  • use '/' to start and '*/' to end comment blocks
  • use '/<' to start one-line inline comments on method params

EA only picks up comments immediately before a construct except for single line comments immediately after an attribute.

EA doesn't require any special formatting to denote that a comment should be included. (eg. /, /, !); standard C++ comment indicators are fine (eg. /*... */, ).

EA doesn't use any positional information ('<' from Doxygen) to determine what a comment belongs to, and it won't trim these characters out.

EA recognises the '@param' command in a method comment and adds the note into the parameter instead of the method. Other commands that do this are '@author' (on a class) and '@version'. NOTE: In EA, Doxygen special commands starting with '\' are treated as ordinary text.

Any javadoc commands that EA doesn't know about are kept in the class or method notes. The ones that are removed are placed somewhere else and will be maintained through round trip engineering.

For example, taking into consideration the LSST requirement for both Doxygen documentation and EA reverse engineering:

/** This comment belongs to Class1 in EA and Doxygen
 */
class Class1
{
      // This comment belongs to attribute1 only in EA
      int attribute1;
      int attribute2; /**< This comment belongs to attribute2 in EA and Doxygen
      int attribute3; /**< This comment belongs to attribute3 only in Doxygen
                           because it covers multiple lines */

      /** This comment belongs to method1 in EA and Doxygen*/
      int method1();

      int method2();  /**< This comment belongs to method2 only in Doxygen
      int method3(int attribute4, int attribute5, int attribute6);
};

enum Foo { }; /**< This comment belongs to Foo only in Doxygen

/** This comment belongs to method3 in EA and Doxygen
    @param attribute4   This comment belongs to attribute4 in EA and Doxygen
    param attribute5   This comment belongs to attribute5 only in Doxygen
 */
int Class1::method3(int attribute4,
                int attribute5,
                int attribute6  /**< This belongs to attribute6 in EA & Doxygen
     ){};

Known problems with EA Reverse Engineering Cycle

Some of the following problems have workarounds, others do not. Those constructs causing failures should be positioned at the end of the source file so that other method definitions are not lost due to the EA parser's exit.

EA Parser Failures (circa EA V818)

The following are known problems which will be fixed in a future EA release.

  • "template static void set_footprint_array_ids<int>(...)" should be rewritten to: "template <typename int> static void set_footprint_array_ids<int>(...)"
  • SWIG generates files which are EA-unparsable code. A blank, introduced after "x:" ''' in ''' "swig_getmethods["xalloc"] = lambda x: xalloc" , needs to be removed prior to EA ingest in "swig_getmethods["xalloc"] = lambda x:xalloc" TBD: should work in EA release after V818

EA Parser Failures in previous EA Installation (EA V818)

The following are fixed when installing into a brand-new project in EA V818. However, they are still not working in our project which was migrated to EA V818. EA is working with us to solve the migration problem.

  • "template long long ..."
  • "template <x> template <y> method(..."