Bug report #16710

sipify.pl drops all but first word from comments

Added by Sandro Santilli almost 7 years ago. Updated over 6 years ago.

Status:Closed
Priority:High
Assignee:Denis Rouzaud
Category:Python bindings / sipify
Affected QGIS version:master Regression?:No
Operating System: Easy fix?:No
Pull Request or Patch supplied:No Resolution:wontfix
Crashes QGIS or corrupts data:No Copied to github as #:24609

Description

This diff was introduced by `git commit` (which in turn calls sipify_all.sh:


--- a/python/core/geometry/qgsabstractgeometry.sip
+++ b/python/core/geometry/qgsabstractgeometry.sip
@@ -59,7 +59,7 @@ class QgsAbstractGeometry

     enum SegmentationToleranceType
     {
-      // Maximum external angle between segments, in radians
+      // Maximum
       MaximumAngle,
       MaximumDifference
     };

Basically I cannot write more than a single word in there, it gets truncated to one word on first git commit

History

#1 Updated by Sandro Santilli almost 7 years ago

  • Subject changed from sipify_all.sh drops all but first word from comments to sipify.pl drops all but first word from comments

#2 Updated by Sandro Santilli almost 7 years ago

  • Assignee changed from Jürgen Fischer to Denis Rouzaud

It is sipify.pl doing the mungling, could be this block:

    # save comments and do not print them, except in SIP_RUN                    
    if ( $SIP_RUN == 0 ){                                                       
        if ( $LINE =~ m/^\s*\/\// ){                                            
            if ($LINE =~ m/^\s*\/\/\!\s*(.*?)\n?$/){                            
                $COMMENT = processDoxygenLine( $1 );                            
                $COMMENT =~ s/\n+$//;                                           
            }                                                                   
            elsif ($INPUT_LINES[$LINE_IDX-1] !~ m/\*\/.*/) {                    
                $COMMENT = '';                                                  
            }                                                                   
            next;                                                               
        }                                                                       
    }

#4 Updated by Nyall Dawson almost 7 years ago

I suspect it's because your doxygen tags are malformed. They should be:

enum SegmentationToleranceType {
MaximumAngle, //!< Maximum external angle between segments, in radians
MaximumDifference
};

Note the important inclusion of the <, which is used whenever the doxygen comment comes AFTER the member (as is the case with enum values)

#5 Updated by Nyall Dawson almost 7 years ago

  • Status changed from Open to Feedback

#6 Updated by Sandro Santilli almost 7 years ago

  • Status changed from Feedback to Open

Nyall moving the comment from above the enum value to its right side with '//!<' prefix makes it completely disappear from the .sip file.

#7 Updated by Nyall Dawson almost 7 years ago

That's by design - sip doesn't support documentation for enumeration values.

#8 Updated by Denis Rouzaud almost 7 years ago

  • Status changed from Open to Closed
  • Category changed from Build/Install to Python bindings / sipify

indeed sip does not support docstrings for bindings and the policy is just to remove them from source.

#9 Updated by Sandro Santilli almost 7 years ago

  • Status changed from Closed to Reopened

If the policy is to remove them from output it is not working, as the very first word after the comment is being retained.

#10 Updated by Sandro Santilli almost 7 years ago

So Nyall and Denis: do you think https://github.com/qgis/QGIS/pull/4728 should be merged with the sip-generated broken comment in here: https://github.com/qgis/QGIS/pull/4728/files#diff-c57e05913a8dc3395f4b0f7d7f926293L61 ?

Those comments in .sip file basically become:

    enum SegmentationToleranceType
    {
      // Maximum
      // to
      MaximumAngle,
      // Maximum
      // curve
      MaximumDifference
    };

#11 Updated by Denis Rouzaud over 6 years ago

  • Status changed from Reopened to Closed

#12 Updated by Sandro Santilli over 6 years ago

  • Status changed from Closed to Reopened

Why closed ? Was it fixed ? If so by which commit ?

#13 Updated by Denis Rouzaud over 6 years ago

No issue here to me. The enum docs are not exported to sip files as they are not used.
As Nyall suggested you can use //!< which makes it a little nicer.

#14 Updated by Giovanni Manghi over 6 years ago

Denis Rouzaud wrote:

No issue here to me. The enum docs are not exported to sip files as they are not used.
As Nyall suggested you can use //!< which makes it a little nicer.

so "won't fix"?

#15 Updated by Denis Rouzaud over 6 years ago

  • Resolution set to wontfix
  • Status changed from Reopened to Closed

Also available in: Atom PDF