Cleanup header documentation

[JoFrhwld]

The top of extractFormants.py has a large comment block that should be preserved somewhere, but is more appropriate in some more visible and (and updatable) documentation.

[chrisbrickhouse]

should be preserved somewhere

It looks like an old change log, but without dates (blame says it was you and Kyle who added them across two commits). We could stash it in a CHANGELOG.md file and/or on a Sphinx page, and this could be updated with future change logs (we should probably have this anyway). I'm not sure how useful preserving this comment block would be given that it's available in the commit history and at least 9 years old, but I don't see much harm.

[JoFrhwld]

The comment block was actually written by Ingrid Rosenfelder, and the two commits would have been the original commit to github, Kyle's commit was from running autopep8.

While there's some changelog components, it also contains documentation. Most important, I think, are this description of the default measurement point selection procedure:

    # - FAAV measurement procedure:                                               ##
    # - AY has 50 ms left padding and is measured at maximum F1              ##
    # - Tuw measured at beginning of segment                                 ##
    # - OW, AW measured halfway between beginning of segment and F1 maximum  ##
    # - EY is measured at maximum F1, but without extra padding              ##

And this discussion of tokens excluded from analysis:

    # - excluded from analysis:                                                   ##
    # - uncertain and unclear transcriptions                                 ##
    # - overlaps                                                             ##
    # - last syllables of truncated words                                    ##

Edit:

It might be silly, but I almost want to save # !!! This is NOT the original extractFormants.py file !!! ##, for posterity. The "original extractFormants.py" would have been a script written by Keelan Evanini for his PhD, which laid the methodological foundations for FAVE

[chrisbrickhouse]

Ah okay, I wasn't sure if those were documentation or just really brief change log entries. Those seem worth adding to the top-level doc string.

It might be silly, but I almost want to save # !!! This is NOT the original extractFormants.py file !!! ##, for posterity.

I'm down for that. We should keep it as an inline comment though. If we add it to the doc string, it will get added to the Sphinx docs which could confuse people.

[chrisbrickhouse]

Oh, we also have NEWS.md where we can stash most of the changelog stuff, right?