@@ -8,7 +8,7 @@ def apicoverage_builder(target, source, env): print 'Building API coverage report...', sys.stdout.flush() f = open(str(target[0]), 'w') - apicoverage.generate_api_coverage('.',f) + apicoverage.generate_api_coverage(['kroll', 'modules'], f) print 'done' build.env.Append(BUILDERS = {'APICoverage' : Builder( SConscript.docs @@ -135,10 +135,11 @@ } /** - * @tiapi(method=True,name=UI.Dialog.getDialogParameter,since=0.4) get an incoming UI dialog parameter - * @tiarg(for=UI.getDialogParam,name=name,type=string) name of the parameter - * @tiarg(for=UI.getDialogParam,name=default,type=string,optional=True) default value if not found - * @tiresult(for=UI.getDialogParam,type=string) result + * @tiapi(method=True,name=UI.Dialog.getDialogParameter,since=0.4) + * @tiapi Get an incoming UI dialog parameter + * @tiarg[string, name] Name of the parameter + * @tiarg[string, value] Default value of the parameter + * @tiresult[value] The parameter */ dialogWindow.getDialogParameter = function(name, defaultValue) { modules/ti.UI/Resources/all/ui.js @@ -6,13 +6,14 @@ import glob, re, os.path as path import fnmatch, os, sys import simplejson as json +import traceback class GlobDirectoryWalker: # a forward iterator that traverses a directory tree - def __init__(self, directory, pattern="*"): + def __init__(self, directory, patterns=['*']): self.stack = [directory] - self.pattern = pattern + self.patterns = patterns self.files = [] self.index = 0 @@ -31,8 +32,9 @@ class GlobDirectoryWalker: fullname = os.path.join(self.directory, file) if os.path.isdir(fullname) and not os.path.islink(fullname): self.stack.append(fullname) - if fnmatch.fnmatch(file, self.pattern): - return fullname + for pattern in self.patterns: + if fnmatch.fnmatch(file, pattern): + return fullname def convert_type(value): # trivial type conversions @@ -123,38 +125,60 @@ def get_api_names(name): tok.pop(0) return module,'.'.join(tok) +def get_last_method_before(method_index, start): + current_start = None + + method_starts = method_index.keys() + method_starts.sort() + for method_start in method_starts: + print "%s %s" % (method_start, start) + if method_start > start: + break + else: + current_start = method_start + + if current_start: + return method_index[current_start] + else: + return None + def generate_api_coverage(dirs,fs): api_pattern = '@tiapi\(([^\)]*)\)\s+(.*)' arg_pattern = '@tiarg\(([^\)]*)\)\s+(.*)' res_pattern = '@tiresult\(([^\)]*)\)\s+(.*)' dep_pattern = '@tideprecated\(([^\)]*)\)\s+(.*)' - - extensions = ['h','cc','c','cpp','m','mm','js','py','rb'] - files = [] + context_sensitive_api_description = '@tiapi (.*)' + context_sensitive_arg_pattern = '@tiarg\[([^]]+)\](.*)' + context_sensitive_result_pattern = '@tiresult\[([^]]+)\](.*)' + + files = set() apis = {} api_count = 0 file_count = 0 module_count = 0 - for ext in extensions: - for dirname in dirs: - for i in GlobDirectoryWalker(dirname,'*.'+ext): - try: - files.index(i) - except: - files.append(i) + extensions = ['h','cc','c','cpp','m','mm','js','py','rb'] + extensions = ['*.' + x for x in extensions] + for dirname in dirs: + print dirname + for i in GlobDirectoryWalker(dirname, extensions): + files.add(i) for f in files: fh = open(str(f),'r') content = fh.read() found = False match = None + + start_index_to_method = {} + try: for m in re.finditer(api_pattern,content): match = m description,metadata = parse_pattern(m) module_name,fn_name = get_api_names(metadata['name']) + print "adding %s -- %s" % (module_name, fn_name) if not apis.has_key(module_name): apis[module_name] = {} module_count+=1 @@ -163,6 +187,44 @@ def generate_api_coverage(dirs,fs): apis[module_name][fn_name]=api api_count+=1 found = True + + # Record the index of the start of this match so we can + # use context sensitive arguments, etc later. + start_index_to_method[m.start()] = api + + for m in re.finditer(context_sensitive_arg_pattern, content): + match = m + api = get_last_method_before(start_index_to_method, m.start()) + if not api: continue + + print m.group(1) + bits = m.group(1).split(',', 2) + metadata = {} + metadata['for'] = api.name + metadata['type'] = bits[0].strip() + metadata['name'] = bits[1].strip() + metadata['description'] = m.group(2).strip() + if len(bits) > 2: metadata['optional'] = True + api.add_argument(APIArgument(metadata, metadata['description'])) + + for m in re.finditer(context_sensitive_result_pattern, content): + match = m + api = get_last_method_before(start_index_to_method, m.start()) + if not(api): continue + + metadata = {} + metadata['type'] = m.group(1).strip() + metadata['description'] = m.group(2).strip() + metadata['for'] = api.name + api.set_return_type(APIReturnType(metadata, metadata['description'])) + + for m in re.finditer(context_sensitive_api_description, content): + match = m + description = m.group(1) + api = get_last_method_before(start_index_to_method, m.start()) + if api: + api['description'] += ' ' + description.strip() + for m in re.finditer(arg_pattern,content): match = m description,metadata = parse_pattern(m) @@ -183,12 +245,14 @@ def generate_api_coverage(dirs,fs): api.set_deprecated(description,metadata['version']) if found: file_count+=1 - except: + except Exception, e: print "Exception parsing API metadata in file: %s" % str(f) + #print e + #print traceback.print_tb(sys.exc_info()[2]) if match: print "Error was for: %s" % str(match.group(0)) - sys.exit(1) + raise fs.write(json.dumps(apis, sort_keys=True, indent=4)) - print "Found %i APIs for %i modules in %i files" % (api_count,module_count,file_count) \ No newline at end of file + print "Found %i APIs for %i modules in %i files" % (api_count,module_count,file_count) site_scons/apicoverage.py dbb9150822a4f5be4ce0706d74ac78d98ba6b3b3 Martin Robinson mrobinson@appcelerator.com http://github.com/marshall/titanium/commit/9decfe5f61af846ea4a0b2a84cc05ffb745d9eeb 9decfe5f61af846ea4a0b2a84cc05ffb745d9eeb 2009-06-03T20:04:36-07:00 2009-06-03T20:04:36-07:00 Improvements for documentation - Faster generation of API docs - Allow for context sensitive documentation example: /** * @tiapi(method=True,name=API.createDependency,since=0.4) * @tiapi A constructor for dependency objects which does a lot * @tiapi of cool stuff this is a really long description. and * @tiapi can go on indefinitely. * @tiarg[int, type] the type of this dependency (eg API.MODULE) dependency * @tiarg[int, requirement, optional=true] the requirement for this dependency * @tiresult[object] an API.Application which represents blah */ - Fixed documentation for UI.Dialog 26199257a238455bdfc440709736d709a0f4c981 Martin Robinson mrobinson@appcelerator.com