sphinx-contrib / matlabdomain

A Sphinx extension for documenting Matlab code
Other
64 stars 45 forks source link

"Island" comments in the properties section causes parsing of a class to fail #220

Closed BuildingAtom closed 8 months ago

BuildingAtom commented 10 months ago

This warning is thrown when parsing a file that has comments isolated from a variable or another comment. The parsing then proceeds to stop.

WARNING: sphinxcontrib-matlabdomain] Expected property in SomeClass - got (Token.Comment, '% Another comment')

This occurs with a classdef that looks like

classdef SomeClass
    properties
        % some comment

        % Another comment
        prop
    end
end

This still occurs even if there is a property defined above the first comment

classdef SomeClass
    properties
        top_prop
        % some comment

        % Another comment
        prop
    end
end

I suspect this might be occurring because the section in L1125 for long comments terminates after the first break, and its assuming that the next line must be some property name, keyword, or punctuation. Perhaps if it's a comment again, it should discard the prior comment and continue the while loop.

Maybe something like the following may work (L1160 of the same file)? I haven't tested it since I use this inside of a temporary docker.

                            ...
                                except IndexError:
                                    # EOF reached, quit gracefully
                                    break

                        # If we encounter a comment again, reparse starting from here
                        if self.tokens[idx][0] is Token.Comment:
                            continue

                        # with "%:" directive trumps docstring after property
                        if self.tokens[idx][0] is Token.Name:
                            ...
joeced commented 8 months ago

Sorry for the late reply and thanks for the report.

I'll look into this very soon