[Freeciv-Dev] (PR#8787) Add documenting comment to each function (list attached)

["Raimar Falke" <i-freeciv-lists@xxxxxxxxxxxxx>]

<URL: http://rt.freeciv.org/Ticket/Display.html?id=8787 >


I have created a script which finds and lists all functions which
either have no comment or an empty one. The list is given for static
and non-static functions (we may not apply the rules for such comments
on static functions).

Each function should have a meaningful comment. We may relax this for
accessor function.

        Raimar

-- 
 email: rf13@xxxxxxxxxxxxxxxxx
 "Like the ad says, at 300 dpi you can tell she's wearing a
  swimsuit. At 600 dpi you can tell it's wet. At 1200 dpi you
  can tell it's painted on. I suppose at 2400 dpi you can tell
  if the paint is giving her a rash."
    -- Joshua R. Poulson

out.gz
Description: application/gunzip

missing_header.sh
Description: Bourne shell script

import sys,re

startpat='^/[*]{30,80}\s*$'
endpat='^[*]{30,80}/\s*$'

for line in sys.stdin.readlines():
    mo=re.search("^(\S*)\s+(\S*)\s+(\d*)\s+(\S*)\s(.*)$",line)
    assert mo
    assert mo.group(2) in ["function","macro","class"],line+" 
"+repr(mo.group(2))
    if mo.group(2)!="function":
        continue
    descr=mo.group(1)+"("+mo.group(4)+":"+mo.group(3)+")"
    if mo.group(5).find("static")!=-1 and mo.group(5).find("inline")==-1:
        descr="static "+descr
    #print descr,mo.group(5)

    lines=open(mo.group(4)).readlines()[:int(mo.group(3))]
    lines=map(lambda x:x[:-1],lines)
    if not re.search(endpat,lines[-2]):
        print descr+" has no comment"
        continue
    elif re.search(startpat,lines[-4]) and re.search("^\s*[.]*\s*$",lines[-3]):
        print descr+" has an empty comment"
        continue
    elif 0:
        print lines[-4]
        print lines[-3]
        print lines[-2]
        print lines[-1]
        print