Improved autogsdoc to output symbols such as methods in their header declaration

order along the gsdoc files. 

Useful for third-party tools which want to generate final documentation from 
the GSDoc ouput and how the original headers were organized.


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

ChangeLog

@@ -1,3 +1,18 @@
+2010-12-25  Quentin Mathe <quentin.mathe@gmail.com>
+
+	Improved autogsdoc to output symbols such as methods in their header 
+	declaration order along the gsdoc files. 
+	Useful for third-party tools that want to generate final documentation from 
+	the GSDoc ouput and how the original headers were organized.
+	* Tools/autogsdoc.m:
+	Added OrderedSymbolDeclarations.plist file output and cleaning.
+	* Tools/AGSParser.h:
+	* Tools/AGSParser.m:
+	Added orderedSymbolDecls ivar.
+	(-addOrderedSymbolDeclaration:toUnit:, -orderedSymbolDeclarationsByUnit): Added.
+	(-parseMethodsAsDeclarations:): Modified to call 
+	-addOrderedSymbolDeclaration:toUnit:.
+
 2010-12-25  Quentin Mathe <quentin.mathe@gmail.com>
 
 	* Headers/Foundation/NSString.h:

Tools/AGSParser.h

@@ -73,6 +73,7 @@
 
   NSString		*comment;	/** Documentation accumulator. */
   NSMutableDictionary	*info;		/** All information parsed. */
+  NSMutableDictionary   *orderedSymbolDeclsByUnit;
   NSMutableArray	*source;	/** Names of source files. */
   NSCharacterSet	*identifier;	/** Legit char in identifier */
   NSCharacterSet	*identStart;	/** Legit initial char of identifier */
@@ -81,6 +82,7 @@
 }
 
 - (NSMutableDictionary*) info;
+- (NSDictionary *) orderedSymbolDeclarationsByUnit;
 - (id) init;	/** <init> Simple initialiser */
 - (NSMutableArray*) outputs;
 - (unsigned) parseComment;

Tools/AGSParser.m

@@ -140,6 +140,7 @@
   DESTROY(ifStack);
   DESTROY(declared);
   DESTROY(info);
+  DESTROY(orderedSymbolDeclsByUnit);
   DESTROY(comment);
   DESTROY(identifier);
   DESTROY(identStart);
@@ -154,6 +155,23 @@
   return info;
 }
 
+/** Returns the methods, functions and C data types in their header declaration 
+order, by organizing them into arrays as described below. 
+
+Methods are grouped by class, category or protocol references. For example, 
+valid keys could be <em>ClassName</em>, <em>ClassName(CategoryName)</em> and 
+<em>(ProtocolName)</em>.
+
+Functions and C data types are grouped by header file names. For example, 
+<em>AGParser.h</em> would a valid key.
+
+TODO: Collect functions and C data types. Only methods are currently included 
+in the returned dictionary. */
+- (NSDictionary *) orderedSymbolDeclarationsByUnit
+{
+  return orderedSymbolDeclsByUnit;
+}
+
 - (id) init
 {
   NSMutableCharacterSet	*m;
@@ -170,6 +188,7 @@
   identStart = RETAIN([NSCharacterSet characterSetWithCharactersInString:
     @"_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]);
   info = [[NSMutableDictionary alloc] initWithCapacity: 6];
+  orderedSymbolDeclsByUnit = [[NSMutableDictionary alloc] init];
   source = [NSMutableArray new];
   verbose = [[NSUserDefaults standardUserDefaults] boolForKey: @"Verbose"];
   warn = [[NSUserDefaults standardUserDefaults] boolForKey: @"Warn"];
@@ -2897,6 +2916,18 @@ fail:
   return nil;
 }
 
+- (void) addOrderedSymbolDeclaration: (NSString *)aMethodOrFunc toUnit: (NSString *)aUnitName
+{
+  NSMutableArray *orderedSymbolDecls = [orderedSymbolDeclsByUnit objectForKey: aUnitName];
+
+  if (orderedSymbolDecls == nil)
+    {
+      orderedSymbolDecls = [NSMutableArray array];
+      [orderedSymbolDeclsByUnit setObject: orderedSymbolDecls forKey: aUnitName];
+    }
+  [orderedSymbolDecls addObject: aMethodOrFunc];
+}
+
 - (NSMutableDictionary*) parseMethodsAreDeclarations: (BOOL)flag
 {
   NSMutableDictionary	*methods;
@@ -2962,6 +2993,7 @@ fail:
 		 * Just record the method.
 		 */
 		[methods setObject: method forKey: token];
+                [self addOrderedSymbolDeclaration: token toUnit: unitName];
 	      }
 	    else if ((exist = [methods objectForKey: token]) != nil)
 	      {

Tools/autogsdoc.m

@@ -649,6 +649,7 @@ main(int argc, char **argv, char **env)
   NSMutableArray	*sFiles = nil;	// Source
   NSMutableArray	*gFiles = nil;	// GSDOC
   NSMutableArray	*hFiles = nil;	// HTML
+  NSString              *symbolDeclsFile = nil;
   NSMutableSet		*deps = nil;
 #if GS_WITH_GC == 0
   NSAutoreleasePool	*outer = nil;
@@ -680,6 +681,7 @@ main(int argc, char **argv, char **env)
           supposed to).
       4c) Remove index file.
       4d) Remove HTML files corresponding to .gsdoc files in current list.
+      4e) Remove the OrderedSymbolDeclarations plist file
 
    5) Start with "source files".. for each one (hereafter called a "header
       file"):
@@ -810,7 +812,7 @@ main(int argc, char **argv, char **env)
     @"MakeFrames",
     @"\t\tString\t(nil)\n\tIf set, look for DTDs in the given directory",
     @"DTDs",
-    @"\t\tBOOL\t(NO)\n\tif YES, wrap paragraphs delimited by \\n\\n in "
+    @"\tBOOL\t(NO)\n\tif YES, wrap paragraphs delimited by \\n\\n in "
       @"<p> tags when possible",
     @"GenerateParagraphMarkup",
     nil];
@@ -908,6 +910,9 @@ main(int argc, char **argv, char **env)
       [mgr createDirectoryAtPath: documentationDirectory attributes: nil];
     }
 
+  symbolDeclsFile = [documentationDirectory 
+    stringByAppendingPathComponent: @"OrderedSymbolDeclarations.plist"];
+
   proc = [NSProcessInfo processInfo];
   if (proc == nil)
     {
@@ -1180,6 +1185,18 @@ main(int argc, char **argv, char **env)
 		}
 	    }
 	}
+
+      /*
+       * 4e) Remove the OrderedSymbolDeclarations plist file.
+       */
+      if ([mgr fileExistsAtPath: symbolDeclsFile])
+	{
+	  if ([mgr removeFileAtPath: symbolDeclsFile handler: nil] == NO)
+	    {
+	      NSLog(@"Cleaning ... failed to remove %@", symbolDeclsFile);
+	    }
+	}
+
       return 0;
     }
 
@@ -1477,6 +1494,13 @@ main(int argc, char **argv, char **env)
 	      [gFiles addObject: [hfile lastPathComponent]];
 	    }
 	}
+
+      /* 
+       * Ask the parser for the OrderedSymbolDeclarations plist and save it
+       */
+      [[parser orderedSymbolDeclarationsByUnit] writeToFile: symbolDeclsFile 
+                                                 atomically: YES];
+
       informalProtocols = RETAIN([output informalProtocols]);
 #if GS_WITH_GC == 0
       DESTROY(pool);