cleanup postProcess step and output obsolete.json file

utils/apidoc/mdn/util.dart

+#library("util");
+
+#import("../../../frog/lib/node/node.dart");
+#import("dart:json");
+
+// TODO(jacobr): this file conflates pretty printing of the JSON database with
+// filtering the database to select the best matches per file.

[nweiz, 2012/02/08 01:18:40]

This isn't true any more

[Jacob, 2012/02/08 01:20:32]

Done.

+// Separate out the two tasks as quick and dirty coding is correct for pretty
+// printing but more carefully documented code is required for the code
+// filtering the database.
+Map<String, Map> _allProps;
+
+Map<String, Map> get allProps() {
+  if (_allProps == null) {
+    // Database of expected property names for each type in WebKit.
+    _allProps = JSON.parse(fs.readFileSync('data/dartIdl.json', 'utf8'));
+  }
+  return _allProps;
+}
+
+Set<String> matchedTypes;
+
+/** Returns whether the type has any member matching the specified name. */
+bool hasAny(String type, String prop) {
+  final data = allProps[type];
+  return data['properties'].containsKey(prop) ||
+      data['methods'].containsKey(prop) ||
+      data['constants'].containsKey(prop);
+}
+
+/**
+ * Return the members from an [entry] as Map of member names to member
+ * objects.
+ */
+Map getMembersMap(Map entry) {
+  List<Map> rawMembers = entry["members"];
+  final members = {};
+  for (final entry in rawMembers) {
+    members[entry['name']] = entry;
+  }
+  return members;
+}
+
+/**
+ * Score entries using similarity heuristics calculated from the observed and
+ * expected list of members. We could be much less naive and penalize spurious
+ * methods, prefer entries with class level comments, etc. This method is
+ * needed becase we extract entries for each of the top search results for
+ * each class name and rely on these scores to determine which entry was
+ * best.  Typically all scores but one will be zero.  Multiple pages have
+ * non-zero scores when MDN has multiple pages on the same class or pages on
+ * similar classes (e.g. HTMLElement and Element), or pages on Mozilla
+ * specific classes that are similar to DOM classes (Console).
+ */
+num scoreEntry(Map entry, String type) {
+  num score = 0;
+  // TODO(jacobr): consider removing skipped entries completely instead of
+  // just giving them lower scores.
+  if (!entry.containsKey('skipped')) {
+    score++;
+  }
+  if (entry.containsKey("members")) {
+    Map members = getMembersMap(entry);
+    for (String name in members.getKeys()) {
+      if (hasAny(type, name)) {
+        score++;
+      }
+    }
+  }
+  return score;
+}
+
+/**
+ * Given a list of candidates for the documentation for a type, find the one
+ * that is the best.
+ */
+Map pickBestEntry(List entries, String type) {
+  num bestScore = -1;
+  Map bestEntry;
+  for (Map entry in entries) {
+    if (entry != null) {
+      num score = scoreEntry(entry, type);
+      if (score > bestScore) {
+        bestScore = score;
+        bestEntry = entry;
+      }
+    }
+  }
+  return bestEntry;
+}