CODEWITHSUNDEEP
pythonpython-2.7comments
Criso
Criso

Reputation: 397

What is the function of a commented out function and "comma splice"?

I've been dissecting a few bits of code over the past two weeks and I keep seeing some reoccurring themes... For example, what is the point of the following...?

class eventHandler(object):
    def create_event(self, event):
        """A general note here.

        :tagged param event:
            description
        :tagged type event:
            :class: `another class` # I do not understand the comma splices ( ` ).
        """
        # I do not understand why it ends here with no real purpose. Perhaps I'm not catching on to something.

    def next_event(self, event):
        ...
        # Continues with the same logic from above

I have seen it in the Python Module "watchdog" as well as other modules and code snippets from the past that are scattered around on the internet. Is this just a sudo-code format for keeping notes? Were the functions discontinued? Am I just not understanding something in particular?

Edit:

Artagel brought up a good reference, I hadn't read deep enough PEP-0008.

Upvotes: 1

Views: 59

Answers (1)

chepner
chepner

Reputation: 531115

The backquotes probably have meaning to some sort of documentation generator that parses doc strings to produce nicely formatted documentation. They have no meaning in the Python language itself.

create_event is probably a method intended to be implemented by a subclass of eventHandler. The doc string alone is sufficient, syntactically, to serve as the body of the method. Without the doc string, you would need to use the pass statement to serve as a placeholder for a "real" body.

def create_event(self, event):
    pass

Upvotes: 2

Related Questions