Skip to content
This repository has been archived by the owner on Mar 4, 2021. It is now read-only.

Doc source updates #55

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Doc source updates #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2a7cbd3
[docs] Do not import samples by default or the docfixer "import-sampl…
aarononeal Jun 5, 2013
3ff1368
[docs] AppleDocMerger: Check for null (don't die just because a type …
aarononeal Jun 5, 2013
2aab374
[docs] AppleDocMerger: Null fix to create ProcessingContext
aarononeal Jun 5, 2013
7998167
[docs] AppleDocMerger make the missing type count configurable
aarononeal Jun 5, 2013
9e168a4
[docs] Enable missing type count configuration from the docfixer comm…
aarononeal Jun 5, 2013
a863fb8
[docs] docfixer: Make the compiled doc bundle configurable from the c…
aarononeal Jun 5, 2013
e72d4b7
[docs] document-generated-code: Make namespace prefix and Apple doc l…
aarononeal Jun 5, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions tools/docfixer/AppleDocMerger.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,10 @@ public class Options
// Default options
public Options ()
{
ImportSamples = true;
ImportSamples = false;
QuickSummaries = true;
CancellationToken = System.Threading.CancellationToken.None;
ThrowOnMissingTypeCount = 90;
}

// Instruct the merger to take samples from a known repository and use them while merging to replace inline apple samples
Expand Down Expand Up @@ -59,6 +60,9 @@ public Options ()

// Token used to end prematurely the process if needed
public CancellationToken CancellationToken { get; set; }

// Consider it an error (throw) if this many types or more were missing
public int ThrowOnMissingTypeCount { get; set; }
}

class ProcessingContext
Expand Down Expand Up @@ -112,8 +116,8 @@ public AppleDocMerger (Options options)
throw new ArgumentException (string.Format ("DocBase '{0}' isn't valid", options.DocBase), "options.DocBase");

var dbPath = Path.Combine (options.DocBase, "..", "..", "docSet.dsidx");
if (!File.Exists (dbPath))
throw new ArgumentException ("DocBase doesn't contain a valid database file", "options.DocBase");
if (!File.Exists (dbPath))
throw new ArgumentException ("DocBase doesn't contain a valid database file", "options.DocBase");
db = new SQLiteConnection (dbPath);

var samplesPath = string.IsNullOrEmpty (options.SamplesRepositoryPath) ? Path.Combine (options.DocBase, "samples.zip") : options.SamplesRepositoryPath;
Expand Down Expand Up @@ -172,7 +176,7 @@ public void MergeDocumentation ()
if (!options.ImportSamples)
samples.Close (!options.DebugDocs);

if (numOfMissingAppleDocumentation > 90) {
if (numOfMissingAppleDocumentation > options.ThrowOnMissingTypeCount) {
throw new ApplicationException (string.Format ("Too many types were not found on this run ({0}), should be around 60-70 (mostly CoreImage, 3 UIKits, 2 CoreAnimation, 1 Foundation, 1 Bluetooth, 1 iAd",
numOfMissingAppleDocumentation));
}
Expand Down Expand Up @@ -382,6 +386,9 @@ public string GetAppleDocFor (TypeDefinition t)
{
var path = db.CreateCommand ("select zkpath from znode join ztoken on znode.z_pk == ztoken.zparentnode where ztoken.ztokenname like \"" + t.Name + "\"").ExecuteScalar<string> ();

if (path == null)
return null;

return Path.Combine (options.DocBase, "..", path);
}

Expand Down Expand Up @@ -714,6 +721,9 @@ string GetRealAppleDocPath (TypeDefinition t)
}
appledocpath = FixAppleDocPath (t, appledocpath);
}
if (context == null)
context = new ProcessingContext ();

context.CurrentAppleDocPath = appledocpath;

return appledocpath;
Expand Down
26 changes: 23 additions & 3 deletions tools/docfixer/docfixer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ public static int Main2 (string[] args)
{
bool show_help = false;
bool useRawDoc = false;
string docBundle = null;
var mergerOptions = new AppleDocMerger.Options ();

var options = new OptionSet () {
Expand All @@ -52,6 +53,12 @@ public static int Main2 (string[] args)
{ "use-raw-doc",
"Process uncompiled mdoc documentation rather than a bundle",
v => useRawDoc = v != null},
{ "doc-bundle=",
"Process a bundle rather than uncompiled mdoc documentation",
v => docBundle = v},
{ "allow-missing=",
"Allow this many types to be missing before considering it an error",
v => mergerOptions.ThrowOnMissingTypeCount = Int32.Parse(v)},
{ "v|verbose",
"Verbose output",
v => mergerOptions.MergingPathCallback = v != null ? p => Console.WriteLine (p) : (Action<string>)null },
Expand All @@ -70,16 +77,29 @@ public static int Main2 (string[] args)
return 1;
}

if (string.IsNullOrEmpty (monodocPath) || show_help) {
if (string.IsNullOrEmpty (monodocPath) || show_help || (useRawDoc && !string.IsNullOrEmpty(docBundle))) {
ShowHelp (options);
return 0;
}

IMdocArchive mdocArchive = null;
if (useRawDoc)
mdocArchive = new MDocDirectoryArchive (Path.Combine (monodocPath, "en"));
else
mdocArchive = MDocZipArchive.ExtractAndLoad (Path.Combine (monodocPath, ArchiveName));
else {
string bundlePath;
if (!string.IsNullOrEmpty(docBundle)) {
bundlePath = Path.Combine(monodocPath, docBundle);
} else {
bundlePath = Path.Combine(monodocPath, "monomac-lib.zip");
if (!File.Exists(bundlePath))
bundlePath = Path.Combine(monodocPath, "MonoTouch-lib.zip");
}
if (!File.Exists(bundlePath)) {
Console.Error.WriteLine("{0} does not exist", bundlePath);
return 1;
}
mdocArchive = MDocZipArchive.ExtractAndLoad (bundlePath);
}
mergerOptions.MonodocArchive = mdocArchive;
var merger = new AppleDocMerger (mergerOptions);
merger.MergeDocumentation ();
Expand Down
52 changes: 28 additions & 24 deletions tools/docfixer/document-generated-code.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,21 +34,13 @@
using macdoc;

class DocumentGeneratedCode {
#if MONOMAC
Type nso = typeof (MonoMac.Foundation.NSObject);
const string ns = "MonoMac";
const string docBase = "/Developer/Documentation/DocSets/com.apple.adc.documentation.AppleSnowLeopard.CoreReference.docset";
#else
Type nso = typeof (MonoTouch.Foundation.NSObject);
const string ns = "MonoTouch";
const string docBase = "/Library/Developer/Shared/Documentation/DocSets/com.apple.adc.documentation.AppleiOS5_0.iOSLibrary.docset";
#endif

static void Help ()
{
Console.WriteLine ("Usage is: document-generated-code [--appledocs] temp.dll path-to-documentation");
Console.WriteLine ("Usage is: document-generated-code --ns-prefix=<prefix> [--apple-doc-dir=<path>] temp.dll path-to-documentation");
}

static string ns;
static string docBase;
static string assembly_dir;
static Assembly assembly;
static bool mergeAppledocs;
Expand All @@ -63,16 +55,15 @@ static string GetPath (string ns, string typeName, bool notification = false)

static string GetMdocPath (Type t, bool notification = false)
{
var ns = t.Namespace;
var typeName = t.FullName.Substring (ns.Length+1);
if (ns == "MonoTouch.Foundation"){
var typeName = t.Name;
if (t.Namespace == ns){
if (typeName == "NSString2")
typeName = "NSString";
if (typeName == "NSObject2")
typeName = "NSObject";
}

return GetPath (ns, typeName, notification);
return GetPath (t.Namespace, typeName, notification);
}

static XDocument GetDoc (Type t, bool notification = false)
Expand Down Expand Up @@ -195,7 +186,7 @@ static XElement GetXmlNodeFromExport (Type t, XDocument xdoc, string selector)
{
return (from m in xdoc.XPathSelectElements ("Type/Members/Member")
let a = m.XPathSelectElement ("Attributes/Attribute/AttributeName")
where a != null && a.Value.IndexOf ("MonoTouch.Foundation.Export(\"" + selector + "\"") != -1
where a != null && a.Value.IndexOf (ns + ".Foundation.Export(\"" + selector + "\"") != -1
select m).FirstOrDefault ();
}

Expand Down Expand Up @@ -305,7 +296,7 @@ public static void ProcessNotification (Type t, XDocument xdoc, PropertyInfo pi)
var evengArgsType = DocumentNotificationNestedType (t, pi, body.ToString ());

remarks.RemoveAll ();
remarks.Add (XElement.Parse ("<para id='tool-remark'>This constant can be used with the <see cref=\"T:MonoTouch.Foundation.NSNotificationCenter\"/> to register a listener for this notification. This is an NSString instead of a string, because these values can be used as tokens in some native libraries instead of being used purely for their actual string content. The 'notification' parameter to the callback contains extra information that is specific to the notification type.</para>"));
remarks.Add (XElement.Parse ("<para id='tool-remark'>This constant can be used with the <see cref=\"T:" + ns + ".Foundation.NSNotificationCenter\"/> to register a listener for this notification. This is an NSString instead of a string, because these values can be used as tokens in some native libraries instead of being used purely for their actual string content. The 'notification' parameter to the callback contains extra information that is specific to the notification type.</para>"));
remarks.Add (XElement.Parse (String.Format ("<para id='tool-remark'>If you want to subscribe to this notification, you can use the convenience <see cref='T:{0}+Notifications'/>.<see cref='M:{0}+Notifications.Observe{1}'/> method which offers strongly typed access to the parameters of the notification.</para>", t.Name, name)));
remarks.Add (XElement.Parse ("<para>The following example shows how to use the strongly typed Notifications class, to take the guesswork out of the available properties in the notification:</para>"));
remarks.Add (XElement.Parse (String.Format ("<example><code lang=\"c#\">\n" +
Expand Down Expand Up @@ -359,9 +350,9 @@ public static string DocumentNotificationNestedType (Type t, PropertyInfo pi, st
class_summary.Add (XElement.Parse ("<para>Notification posted by the <see cref =\"T:" + t.FullName + "\"/> class.</para>"));
class_remarks.RemoveAll ();
class_remarks.Add (XElement.Parse ("<para>This is a static class which contains various helper methods that allow developers to observe events posted " +
"in the iOS notification hub (<see cref=\"T:MonoTouch.Foundation.NSNotificationCenter\"/>).</para>"));
"in the iOS notification hub (<see cref=\"T:" + ns + ".Foundation.NSNotificationCenter\"/>).</para>"));
class_remarks.Add (XElement.Parse ("<para>The methods defined in this class post events invoke the provided method or lambda with a " +
"<see cref=\"T:MonoTouch.Foundation.NSNotificationEventArgs\"/> parameter which contains strongly typed properties for the notification arguments.</para>"));
"<see cref=\"T:" + ns + ".Foundation.NSNotificationEventArgs\"/> parameter which contains strongly typed properties for the notification arguments.</para>"));

var notifications = from prop in t.GetProperties ()
let propName = prop.Name
Expand Down Expand Up @@ -398,7 +389,7 @@ public static string DocumentNotificationNestedType (Type t, PropertyInfo pi, st
handler.Value = "Method to invoke when the notification is posted.";
summary.Value = "Registers a method to be notified when the " + notification.Item2 + " notification is posted.";
returns.RemoveAll ();
returns.Add (XElement.Parse ("<para>The returned NSObject represents the registered notification. Either call Dispose on the object to stop receiving notifications, or pass it to <see cref=\"M:MonoTouch.Foundation.NSNotificationCenter.RemoveObserver\"/></para>"));
returns.Add (XElement.Parse ("<para>The returned NSObject represents the registered notification. Either call Dispose on the object to stop receiving notifications, or pass it to <see cref=\"M:" + ns + ".Foundation.NSNotificationCenter.RemoveObserver\"/></para>"));
remarks.RemoveAll ();
remarks.Add (XElement.Parse ("<para>The following example shows how you can use this method in your code</para>"));

Expand Down Expand Up @@ -805,12 +796,25 @@ public static int Main (string [] args)
Help ();
return 0;
}
if (arg == "--appledocs"){
if (arg == "--debugdoc"){
debugDoc = true;
continue;
}
if (arg.StartsWith("--apple-doc-dir")) {
mergeAppledocs = true;
var split = arg.Split('=');
if (split.Length == 2)
docBase = split[1];
else
docBase = args[++i];
continue;
}
if (arg == "--debugdoc"){
debugDoc = true;
if (arg.StartsWith("--ns-prefix")) {
var split = arg.Split('=');
if (split.Length == 2)
ns = split[1];
else
ns = args[++i];
continue;
}

Expand All @@ -820,7 +824,7 @@ public static int Main (string [] args)
dir = arg;
}

if (dir == null){
if (dir == null || ns == null || (mergeAppledocs && docBase == null)){
Help ();
return 1;
}
Expand Down