Fix various minor documentation bugs.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@14777 72102866-910b-0410-8b05-ffd578937521

Headers/gnustep/base/NSObject.h

@@ -189,7 +189,7 @@
  * class of the object to be aClass etc.  The allocated memory will
  * be extraBytes larger than the space actually needed to hold the
  * instance variables of the object.<br />
- * This function is used by the [NSObject-allocWithZone:] mnethod.
+ * This function is used by the [NSObject+allocWithZone:] mnethod.
  */
 GS_EXPORT NSObject *
 NSAllocateObject(Class aClass, unsigned extraBytes, NSZone *zone);
@@ -206,7 +206,8 @@ NSDeallocateObject(NSObject *anObject);
  * memory allocated from zone.  The allocated memory will be extraBytes
  * longer than that necessary to actually store the instance variables
  * of the copied object.<br />
- * This is used by the [NSObject-copyWithZone:] method.
+ * This is used by the NSObject implementation of the
+ * [(NSCopying)-copyWithZone:] method.
  */
 GS_EXPORT NSObject *
 NSCopyObject(NSObject *anObject, unsigned extraBytes, NSZone *zone);

Source/NSObjCRuntime.m

@@ -510,7 +510,7 @@ GSGetValue(NSObject *self, NSString *key, SEL sel,
  * supplied).<br />
  * Automatic conversion between NSNumber and C scalar types is performed.<br />
  * If type is null and can't be determined from the selector, the
- * [NSObject-handleTakevalue:forUnboundKey:] method is called to try
+ * [NSObject-handleTakeValue:forUnboundKey:] method is called to try
  * to set a value.
  */
 void

Tools/AGSHtml.m

@@ -188,9 +188,9 @@ static NSMutableSet	*textNodes = nil;
       if (u == nil)
 	{
 	  u = unit;
-	}
 	  s = base;
 	}
+    }
   else if (u == nil)
     {
       if (category == nil)
@@ -215,7 +215,7 @@ static NSMutableSet	*textNodes = nil;
 	  s = [globalRefs unitRef: r type: t unit: &u];
 	}
     }
-  else
+  if (s == nil)
     {
       NSString	*tmp = u;
 
@@ -1448,12 +1448,12 @@ static NSMutableSet	*textNodes = nil;
 	  NSString	*type = [prop objectForKey: @"type"];
 	  NSString	*r = [prop objectForKey: @"id"];
 	  GSXMLNode	*tmp = [node firstChild];
+	  NSString	*c = [prop objectForKey: @"class"];
 	  NSString	*s;
 
 	  if ([type isEqual: @"method"] || [type isEqual: @"ivariable"])
 	    {
-	      s = [prop objectForKey: @"class"];
-	      s = [self makeLink: r ofType: type inUnit: s isRef: YES];
+	      s = [self makeLink: r ofType: type inUnit: c isRef: YES];
 	    }
 	  else
 	    {
@@ -1470,7 +1470,16 @@ static NSMutableSet	*textNodes = nil;
 	    }
 	  if (s == nil)
 	    {
-	      NSLog(@"ref '%@' not found for %@", r, type);
+	      if (c == nil)
+		{
+		  NSLog(@"No unique ref to %@ '%@' not found in %@",
+		    type, r, base);
+		}
+	      else
+		{
+		  NSLog(@"ref to the %@ version of %@ '%@' not found in %@",
+		    c, type, r, base);
+		}
 	      if (tmp == nil)
 		{
 		  [buf appendString: r];

Tools/AGSOutput.m

@@ -69,6 +69,11 @@ static BOOL snuggleStart(NSString *t)
  *  far too special purpose.</p>
  *  <unit />
  *  <p>Here is the afterword for the class.</p>
+ *  <p> Ad here is some automated cross referencing ...
+ *  A method in a protocol: [(NSCopying)-copyWithZone:], a class:
+ *  [NSString], a protocol: [(NSCopying)], and a
+ *  category: [NSRunLoop(GNUstepExtensions)].
+ *  </p>
  * </unit>
  * And finally, here is the actual class description ... outside the chapter.
  * With a reference to foo() in it.
@@ -1809,6 +1814,7 @@ static BOOL snuggleStart(NSString *t)
       /*
        * Ensure that methods are rendered as references.
        * First look for format with class name in square brackets.
+       * If that's all there is, we make a class reference.
        */
       r = [tmp rangeOfString: @"["];
       if (r.length > 0)
@@ -1824,6 +1830,7 @@ static BOOL snuggleStart(NSString *t)
 	      NSString	*cName = nil;
 	      NSString	*mName = nil;
 	      unichar	c;
+	      BOOL	isProtocol = NO;
 
 	      if (pos < ePos
 		&& [identStart characterIsMember:
@@ -1880,8 +1887,7 @@ static BOOL snuggleStart(NSString *t)
 		      cName = [tmp substringWithRange: r];
 		    }
 		}
-	      else if (pos < ePos
-		&& (c = [tmp characterAtIndex: pos]) == '(')
+	      else if (pos < ePos && (c = [tmp characterAtIndex: pos]) == '(')
 		{
 		  /*
 		   * Look for protocol name.
@@ -1903,6 +1909,7 @@ static BOOL snuggleStart(NSString *t)
 			}
 		      pos++;
 		    }
+		  isProtocol = YES;
 		}
 
 	      if (pos < ePos && (c == '+' || c == '-'))
@@ -1986,6 +1993,23 @@ static BOOL snuggleStart(NSString *t)
 		      ref = [NSString stringWithFormat:
 			@"<ref type=\"method\" id=\"%@\">", mName];
 		    }
+		  else if (isProtocol == YES)
+		    {
+		      ref = [NSString stringWithFormat:
+			@"<ref type=\"method\" id=\"%@\" class=\"%@\">",
+			mName, cName];
+		      if (isProtocol == YES)
+			{
+			  if (sub == nil)
+			    {
+			      sub = tmp;
+			    }
+			  sub = [sub stringByReplacingString: @"("
+						  withString: @"&lt;"];
+			  sub = [sub stringByReplacingString: @")"
+						  withString: @"&gt;"];
+			}
+		    }
 		  else
 		    {
 		      ref = [NSString stringWithFormat:
@@ -2005,6 +2029,34 @@ static BOOL snuggleStart(NSString *t)
 		      [a insertObject: end atIndex: ++l];
 		    }
 		}
+	      else if (pos == ePos && cName != nil)
+		{
+		  NSString	*ref;
+
+		  if (isProtocol == YES)
+		    {
+		      NSRange	r;
+
+		      r = NSMakeRange(1, [cName length] - 2);
+		      cName = [cName substringWithRange: r];
+		      ref = [NSString stringWithFormat:
+			@"<ref type=\"protocol\" id=\"(%@)\">&lt;%@&gt;</ref>",
+			cName, cName];
+		    }
+		  else if ([cName hasSuffix: @")"] == YES)
+		    {
+		      ref = [NSString stringWithFormat:
+			@"<ref type=\"category\" id=\"%@\">%@</ref>",
+			cName, cName];
+		    }
+		  else
+		    {
+		      ref = [NSString stringWithFormat:
+			@"<ref type=\"class\" id=\"%@\">%@</ref>",
+			cName, cName];
+		    }
+		  [a replaceObjectAtIndex: l withObject: ref];
+		}
 	    }
 	  continue;
 	}

Tools/autogsdoc.m

@@ -20,6 +20,8 @@
 
 <chapter>
   <heading>The autogsdoc tool</heading>
+  <section>
+    <heading>overview</heading>
     <p>
       The autogsdoc tool is a command-line utility for parsing ObjectiveC
       source code (header files and optionally source files) in order to
@@ -57,6 +59,9 @@
       the end of the first chapter of the document (it creates the first
       chapter if necessary).
     </p>
+  </section>
+  <section>
+    <heading>Extra markup</heading>
     <p>
       There are some cases where special extra processing is performed,
       predominantly in the first comment found in the source file,
@@ -143,6 +148,9 @@
 	construct a value from the RCS Revision tag (if available).
       </item>
     </list>
+  </section>
+  <section>
+    <heading>Method markup</heading>
     <p>
       In comments being used to provide text for a method description, the
       following markup is removed from the text and handled specially -
@@ -165,6 +173,9 @@
 	conforming (or not conforming) to the specified standards.
       </item>
     </list>
+  </section>
+  <section>
+    <heading>Automated markup</heading>
     <p>
       Generally, the text in comments is reformatted to standardise and
       indent it nicely ... the reformatting is <em>not</em> performed on
@@ -186,8 +197,8 @@
 	class or, if only one known class had an init method, it
 	would refer to the method of that class.
 	<br />Note the fact that the method name must be surrounded by
-      whitespace (though a comma, fullstop, or semicolon at the end
-      of the specifier will also act as a whitespace terminator).
+	whitespace to be recognized (though a comma, fullstop, or semicolon
+	at the end of the specifier will act like whitespace).
       </item>
       <item>Method specifiers including class names (beginning and ending with
 	square brackets) are enclosed in &lt;ref...&gt; ... &lt;/ref&gt; markup.
@@ -202,6 +213,12 @@
 	the customary angle brackets, because gsdoc is an XML language, and
 	XML treats angle brackets specially.
       </item>
+      <item>Class names (and also protocol and category names) enclosed
+	in square brackets are also cross referenced.
+	<br />Protocol names are enclosed in round brackets rather than
+	the customary angle brackets, because gsdoc is an XML language, and
+	XML treats angle brackets specially.
+      </item>
       <item>Function names (ending with '()') other than 'main()' are enclosed
 	in &lt;ref...&gt; ... &lt;/ref&gt; markup.<br />
 	eg. "NSLogv()" (without the quotes) would be wrapped in a gsdoc
@@ -211,6 +228,9 @@
 	of the specifier will also act as a whitespace terminator).
       </item>
     </list>
+  </section>
+  <section>
+    <heading>Arguments and Defaults</heading>
     <p>
       The tools accepts certain user defaults (which can of course be
       supplied as command-line arguments as usual) -
@@ -223,8 +243,8 @@
 	which would be generated from gsdoc files listed explicitly),
 	and finally removes the project index file.<br />
 	The only exception to this is that template gsdoc files (ie those
-      specifield using ConstantsTemplate, FunctionsTemplate arguments etc)
-      are not deleted unless the CleanTemplates flag is set.
+	specifield using "-ConstantsTemplate ...", "-FunctionsTemplate ..."
+        arguments etc) are not deleted unless the CleanTemplates flag is set.
       </item>
       <item><strong>CleanTemplates</strong>
 	This flag specifies whether template gsdoc files are to be removed
@@ -254,7 +274,7 @@
 	If this default is not specified, the full name of the header file
 	(as supplied on the command line), with the HeaderDirectory
 	default prepended, is used.<br />
-      A typical usage of this might be <code>-Declared Foundation</code>
+	A typical usage of this might be <code>"-Declared Foundation"</code>
 	when generating documentation for the GNUstep base library.  This
 	would result in the documentation saying that NSString is declared
 	in <code>Foundation/NSString.h</code>
@@ -324,7 +344,7 @@
 	NB. Local projects with the same name as the project currently
 	being documented will <em>not</em> be included by this mechanism.
 	If you wish to include such projects, you must do so explicitly
-      using <em>-Projects</em>
+	using <em>"-Projects ..."</em>
       </item>
       <item><strong>MacrosTemplate</strong>
 	Specify the name of a template document into which documentation
@@ -385,7 +405,7 @@
 	NB. System projects with the same name as the project currently
 	being documented will <em>not</em> be included by this mechanism.
 	If you wish to include such projects, you must do so explicitly
-      using <em>-Projects</em>
+	using <em>"-Projects ..."</em>
       </item>
       <item><strong>TypedefsTemplate</strong>
 	Specify the name of a template document into which documentation
@@ -442,6 +462,7 @@
 	Two slashes ('//') - the rest of the line is ignored.<br />
       </item>
     </list>
+  </section>
   <section>
     <heading>Inter-document linkage</heading>
     <p>

Tools/gsdoc-1_0_0.dtd

@@ -149,7 +149,7 @@
 <!ELEMENT ref (%text;)*>
 <!ATTLIST ref
   id CDATA #REQUIRED
-  type (class|protocol|method|ivariable|function|type|macro|variable|constant|label|EOModel|EOEntity) "label"
+  type (class|category|protocol|method|ivariable|function|type|macro|variable|constant|label|EOModel|EOEntity) "label"
   class CDATA #IMPLIED
 >