# checkLibraryDoc.tcl --

#

# This script attempts to determine what APIs exist in the source base that 

# have not been documented.  By grepping through all of the doc/*.3 man 

# pages, looking for "Pkg_*" (e.g., Tcl_ or Tk_), and comparing this list

# against the list of Pkg_ APIs found in the source (e.g., tcl8.2/*/*.[ch])

# we create six lists:

#      1) APIs in Source not in Docs.

#      2) APIs in Docs not in Source.

#      3) Internal APIs and structs.

#      4) Misc APIs and structs that we are not documenting.

#      5) Command APIs (e.g., Tcl_ArrayObjCmd.)

#      6) Proc pointers (e.g., Tcl_CloseProc.)

# 

# Note: Each list is "a best guess" approximation.  If developers write

# non-standard code, this script will produce erroneous results.  Each

# list should be carefully checked for accuracy. 

#

# Copyright (c) 1998-1999 by Scriptics Corporation.

# All rights reserved.

# 

# RCS: @(#) $Id: checkLibraryDoc.tcl,v 1.7 2002/01/15 17:55:30 dgp Exp $

lappend auto_path "c:/program\ files/tclpro1.2/win32-ix86/bin"

#lappend auto_path "/home/surles/cvs/tclx8.0/tcl/unix"

if {[catch {package require Tclx}]} {

    puts "error: could not load TclX.  Please set TCL_LIBRARY."

    exit 1

}

# A list of structs that are known to be undocumented.

set StructList {

    Tcl_AsyncHandler \

    Tcl_CallFrame \

    Tcl_Condition \

    Tcl_Encoding \

    Tcl_EncodingState \

    Tcl_EncodingType \

    Tcl_HashEntry \

    Tcl_HashSearch \

    Tcl_HashTable \

    Tcl_Mutex \

    Tcl_Pid \

    Tcl_QueuePosition \

    Tcl_ResolvedVarInfo \

    Tcl_SavedResult \

    Tcl_ThreadDataKey \

    Tcl_ThreadId \

    Tcl_Time \

    Tcl_TimerToken \

    Tcl_Token \

    Tcl_Trace \

    Tcl_Value \

    Tcl_ValueType \

    Tcl_Var \

    Tk_3DBorder \

    Tk_ArgvInfo \

    Tk_BindingTable \

    Tk_Canvas \

    Tk_CanvasTextInfo \

    Tk_ConfigSpec \

    Tk_ConfigTypes \

    Tk_Cursor \

    Tk_CustomOption \

    Tk_ErrorHandler \

    Tk_FakeWin \

    Tk_Font \

    Tk_FontMetrics \

    Tk_GeomMgr \

    Tk_Image \

    Tk_ImageMaster \

    Tk_ImageType \

    Tk_Item \

    Tk_ItemType \

    Tk_OptionSpec\

    Tk_OptionTable \

    Tk_OptionType \

    Tk_PhotoHandle \

    Tk_PhotoImageBlock \

    Tk_PhotoImageFormat \

    Tk_PostscriptInfo \

    Tk_SavedOption \

    Tk_SavedOptions \

    Tk_SegType \

    Tk_TextLayout \

    Tk_Window \

}

# Misc junk that appears in the comments of the source.  This just 

# allows us to filter comments that "fool" the script.

set CommentList {

    Tcl_Create\[Obj\]Command \

    Tcl_DecrRefCount\\n \

    Tcl_NewObj\\n \

    Tk_GetXXX \

}

# Main entry point to this script.

proc main {} {

    global argv0 

    global argv 

    set len [llength $argv]

    if {($len != 2) && ($len != 3)} {

	puts "usage: $argv0 pkgName pkgDir \[outFile\]"

	puts "   pkgName == Tcl,Tk"

	puts "   pkgDir  == /home/surles/cvs/tcl8.2"

	exit 1

    }

    set pkg [lindex $argv 0]

    set dir [lindex $argv 1]

    if {[llength $argv] == 3} {

	set file [open [lindex $argv 2] w]

    } else {

	set file stdout

    }

    foreach {c d} [compare [grepCode $dir $pkg] [grepDocs $dir $pkg]] {}

    filter $c $d $dir $pkg $file

    if {$file != "stdout"} {

	close $file

    }

    return

}

# Intersect the two list and write out the sets of APIs in one

# list that is not in the other.

proc compare {list1 list2} {

    set inter [intersect3 $list1 $list2]

    return [list [lindex $inter 0] [lindex $inter 2]]

}

# Filter the lists into the six lists we report on.  Then write

# the results to the file.

proc filter {code docs dir pkg {outFile stdout}} {

    set apis  {}

    # A list of Tcl command APIs.  These are not documented.

    # This list should just be verified for accuracy.

    set cmds  {}

    # A list of proc pointer structs.  These are not documented.

    # This list should just be verified for accuracy.

    set procs {}

    # A list of internal declarations.  These are not documented.

    # This list should just be verified for accuracy.

    set decls [grepDecl $dir $pkg]

    # A list of misc. procedure declarations that are not documented.

    # This list should just be verified for accuracy.

    set misc [grepMisc $dir $pkg]

    set pat1 ".*(${pkg}_\[A-z0-9]+).*$"

    # A list of APIs in the source, not in the docs.

    # This list should just be verified for accuracy.

    foreach x $code {

	if {[string match *Cmd $x]} {

	    if {[string match ${pkg}* $x]} {

		lappend cmds $x

	    }

	} elseif {[string match *Proc $x]} {

	    if {[string match ${pkg}* $x]} {

		lappend procs $x

	    }

	} elseif {[lsearch -exact $decls $x] >= 0} {

	    # No Op.

	} elseif {[lsearch -exact $misc $x] >= 0} {

	    # No Op.

	} else {

	    lappend apis $x

	}

    }

    dump $apis  "APIs in Source not in Docs." $outFile

    dump $docs  "APIs in Docs not in Source." $outFile

    dump $decls "Internal APIs and structs."  $outFile

    dump $misc  "Misc APIs and structs that we are not documenting." $outFile

    dump $cmds  "Command APIs."  $outFile

    dump $procs "Proc pointers." $outFile

    return

}

# Print the list of APIs if the list is not null.

proc dump {list title file} {

    if {$list != {}} {

	puts $file ""

	puts $file $title

	puts $file "---------------------------------------------------------"

	foreach x $list {

	    puts $file $x

	}

    }

}

# Grep into "dir/*/*.[ch]" looking for APIs that match $pkg_*.

# (e.g., Tcl_Exit).  Return a list of APIs.

proc grepCode {dir pkg} {

    set apis [myGrep "${pkg}_\.\*" "${dir}/\*/\*\.\[ch\]"]

    set pat1 ".*(${pkg}_\[A-z0-9]+).*$"

    foreach a $apis {

	if {[regexp --  $pat1 $a main n1]} {

	    set result([string trim $n1]) 1

	}

    }

    return [lsort [array names result]]

}

# Grep into "dir/doc/*.3" looking for APIs that match $pkg_*.

# (e.g., Tcl_Exit).  Return a list of APIs.

proc grepDocs {dir pkg} {

    set apis [myGrep "\\fB${pkg}_\.\*\\fR" "${dir}/doc/\*\.3"]

    set pat1 ".*(${pkg}_\[A-z0-9]+)\\\\fR.*$"

    foreach a $apis {

	if {[regexp -- $pat1 $a main n1]} {

	    set result([string trim $n1]) 1

	}

    }

    return [lsort [array names result]]

}

# Grep into "generic/pkgIntDecls.h" looking for APIs that match $pkg_*.

# (e.g., Tcl_Export).  Return a list of APIs.

proc grepDecl {dir pkg} {

    set file [file join $dir generic "[string tolower $pkg]IntDecls.h"] 

    set apis [myGrep "^EXTERN.*\[ \t\]${pkg}_.*" $file]

    set pat1 ".*(${pkg}_\[A-z0-9]+).*$"

    foreach a $apis {

	if {[regexp -- $pat1 $a main n1]} {

	    set result([string trim $n1]) 1

	}

    }

    return [lsort [array names result]]

}

# Grep into "*/*.[ch]" looking for APIs that match $pkg_Db*.

# (e.g., Tcl_DbCkalloc).  Return a list of APIs.

proc grepMisc {dir pkg} {

    global CommentList

    global StructList

    set apis [myGrep "^EXTERN.*\[ \t\]${pkg}_Db.*" "${dir}/\*/\*\.\[ch\]"]

    set pat1 ".*(${pkg}_\[A-z0-9]+).*$"

    foreach a $apis {

	if {[regexp -- $pat1 $a main n1]} {

	    set dbg([string trim $n1]) 1

	}

    }

    set result {}

    eval {lappend result} $StructList

    eval {lappend result} [lsort [array names dbg]]

    eval {lappend result} $CommentList

    return $result

}

proc myGrep {searchPat globPat} {

    set result {}

    foreach file [glob -nocomplain $globPat] {

	set file [open $file r]

	set data [read $file]

	close $file

	foreach line [split $data "\n"] {

	    if {[regexp "^.*${searchPat}.*\$" $line]} {

		lappend result $line

	    }

	}

    }

    return $result

}

main