Add docblocks to tags

entry.c

@@ -761,6 +761,11 @@ static int addExtensionFields (const tagEntryInfo *const tag)
 		length += fprintf (TagFile.fp, "%s\tsignature:%s", sep,
 				tag->extensionFields.signature);
 
+	if (Option.extensionFields.docblock  &&
+			tag->extensionFields.docblock != NULL)
+		length += fprintf (TagFile.fp, "%s\tdocblock:%s", sep,
+				tag->extensionFields.docblock);
+
 	return length;
 #undef sep
 }

entry.h

@@ -72,6 +72,7 @@ typedef struct sTagEntryInfo {
 		const char* inheritance;
 		const char* scope [2];    /* value and key */
 		const char* signature;
+		const char* docblock;
 
 		/* type (union/struct/etc.) and name for a variable or typedef. */
 		const char* typeRef [2];  /* e.g., "struct" and struct name */

options.c

@@ -119,7 +119,8 @@ optionValues Option = {
 		FALSE,  /* -fields=n */
 		TRUE,   /* -fields=s */
 		FALSE,  /* -fields=S */
-		TRUE    /* -fields=t */
+		TRUE,   /* -fields=t */
+		FALSE   /* -fields=d */
 	},
 	NULL,       /* -I */
 	FALSE,      /* -a */
@@ -208,7 +209,7 @@ static optionDescription LongOptionDescription [] = {
  {1,"  --extra=[+|-]flags"},
  {1,"      Include extra tag entries for selected information (flags: \"fq\")."},
  {1,"  --fields=[+|-]flags"},
- {1,"      Include selected extension fields (flags: \"afmikKlnsStz\") [fks]."},
+ {1,"      Include selected extension fields (flags: \"afmikKlnsStzd\") [fks]."},
  {1,"  --file-scope=[yes|no]"},
  {1,"       Should tags scoped only for a single file (e.g. \"static\" tags"},
  {1,"       be included in the output [yes]?"},
@@ -859,6 +860,7 @@ static void processFieldsOption (
 		case 'S': field->signature      = mode; break;
 		case 'z': field->kindKey        = mode; break;
 		case 't': field->typeRef        = mode; break;
+		case 'd': field->docblock       = mode; break;
 
 		default: error(WARNING, "Unsupported parameter '%c' for \"%s\" option",
 					c, option);

options.h

@@ -78,6 +78,7 @@ struct sExtFields {  /* extension field content control */
 	boolean scope;
 	boolean signature;
 	boolean typeRef;
+	boolean docblock;
 };
 
 /*  This stores the command line options.

php.c

@@ -22,6 +22,7 @@
 #include "routines.h"
 #include "debug.h"
 
+#include <string.h>
 
 #define SCOPE_SEPARATOR "::"
 
@@ -237,6 +238,7 @@ static boolean InPhp = FALSE; /* whether we are between <? ?> */
 struct {
 	accessType access;
 	implType impl;
+	vString* docblock;
 } CurrentStatement;
 
 /* Current namespace */
@@ -280,8 +282,32 @@ static const char *implToString (const implType impl)
 	return names[impl];
 }
 
+static void encodeDocBlock (vString *const encoded, vString const *docblock)
+{
+	int i, len;
+	char *buff, c;
+	buff = vStringValue (docblock);
+	len = strlen (buff);
+
+	vStringClear (encoded);
+
+	for (i = 0; i < len; ++i) {
+		c = buff[i];
+		if (c == '\n')
+			vStringCatS (encoded, "\\n");
+		else if (c == '\r')
+			vStringCatS (encoded, "\\r");
+		else if (c == '\t')
+			vStringCatS (encoded, "\\t");
+		else
+			vStringPut (encoded, c);
+
+	}
+	vStringTerminate (encoded);
+}
+
 static void initPhpEntry (tagEntryInfo *const e, const tokenInfo *const token,
-						  const phpKind kind, const accessType access)
+						  const phpKind kind, const accessType access, vString *const docblock)
 {
 	static vString *fullScope = NULL;
 	int parentKind = -1;
@@ -321,6 +347,10 @@ static void initPhpEntry (tagEntryInfo *const e, const tokenInfo *const token,
 		e->extensionFields.scope[0] = PhpKinds[parentKind].name;
 		e->extensionFields.scope[1] = vStringValue (fullScope);
 	}
+	if (vStringLength (docblock) > 0)
+	{
+		e->extensionFields.docblock = vStringValue (docblock);
+	}
 }
 
 static void makeSimplePhpTag (const tokenInfo *const token, const phpKind kind,
@@ -330,7 +360,7 @@ static void makeSimplePhpTag (const tokenInfo *const token, const phpKind kind,
 	{
 		tagEntryInfo e;
 
-		initPhpEntry (&e, token, kind, access);
+		initPhpEntry (&e, token, kind, access, CurrentStatement.docblock);
 		makeTagEntry (&e);
 	}
 }
@@ -359,7 +389,7 @@ static void makeClassOrIfaceTag (const phpKind kind, const tokenInfo *const toke
 	{
 		tagEntryInfo e;
 
-		initPhpEntry (&e, token, kind, ACCESS_UNDEFINED);
+		initPhpEntry (&e, token, kind, ACCESS_UNDEFINED, CurrentStatement.docblock);
 
 		if (impl != IMPL_UNDEFINED)
 			e.extensionFields.implementation = implToString (impl);
@@ -373,12 +403,12 @@ static void makeClassOrIfaceTag (const phpKind kind, const tokenInfo *const toke
 static void makeFunctionTag (const tokenInfo *const token,
 							 const vString *const arglist,
 							 const accessType access, const implType impl)
-{ 
+{
 	if (PhpKinds[K_FUNCTION].enabled)
 	{
 		tagEntryInfo e;
 
-		initPhpEntry (&e, token, K_FUNCTION, access);
+		initPhpEntry (&e, token, K_FUNCTION, access, CurrentStatement.docblock);
 
 		if (impl != IMPL_UNDEFINED)
 			e.extensionFields.implementation = implToString (impl);
@@ -514,6 +544,18 @@ static int skipToCharacter (const int c)
 	return d;
 }
 
+static int collectToCharacter (vString *const string, const int c)
+{
+	int d;
+	do
+	{
+		d = fileGetc ();
+		vStringPut (string, (char) d);
+	} while (d != EOF  &&  d != c);
+	vStringTerminate (string);
+	return d;
+}
+
 static void parseString (vString *const string, const int delimiter)
 {
 	while (TRUE)
@@ -673,7 +715,7 @@ static int skipWhitespaces (int c)
 }
 
 /* <script[:white:]+language[:white:]*=[:white:]*(php|'php'|"php")[:white:]*>
- * 
+ *
  * This is ugly, but the whole "<script language=php>" tag is and we can't
  * really do better without adding a lot of code only for this */
 static boolean isOpenScriptLanguagePhp (int c)
@@ -906,9 +948,24 @@ static void readToken (tokenInfo *const token)
 			}
 			else if (d == '*')
 			{
+				boolean isDocBlock = FALSE;
+				int d2 = fileGetc ();
+				vString *docblock = NULL;
+				if (d2 == '*') {
+					isDocBlock = TRUE;
+					docblock = vStringNew ();
+				}
+				else
+					fileUngetc (d2);
+
+
 				do
 				{
-					c = skipToCharacter ('*');
+					if (isDocBlock == FALSE)
+						c = skipToCharacter ('*');
+					else
+						c = collectToCharacter (docblock, '*');
+
 					if (c != EOF)
 					{
 						c = fileGetc ();
@@ -918,6 +975,18 @@ static void readToken (tokenInfo *const token)
 							fileUngetc (c);
 					}
 				} while (c != EOF && c != '\0');
+				if (isDocBlock) {
+					vString *encoded = vStringNew ();
+					encodeDocBlock (encoded, docblock);
+					vStringDelete (docblock);
+
+					vStringClear (CurrentStatement.docblock);
+					vStringCatS (CurrentStatement.docblock, "/**");
+					vStringCat  (CurrentStatement.docblock, encoded);
+					vStringCatS (CurrentStatement.docblock, "/");
+
+					vStringDelete (encoded);
+				}
 				goto getNextChar;
 			}
 			else
@@ -1133,7 +1202,13 @@ static boolean parseFunction (tokenInfo *const token, const tokenInfo *name)
 				case TOKEN_OPEN_SQUARE:		vStringPut (arglist, '[');		break;
 				case TOKEN_PERIOD:			vStringPut (arglist, '.');		break;
 				case TOKEN_SEMICOLON:		vStringPut (arglist, ';');		break;
-				case TOKEN_STRING:			vStringCatS (arglist, "'...'");	break;
+				case TOKEN_STRING:
+				{
+					vStringCatS (arglist, "'");
+					vStringCat  (arglist, token->string);
+					vStringCatS (arglist, "'");
+					break;
+				}
 
 				case TOKEN_IDENTIFIER:
 				case TOKEN_KEYWORD:
@@ -1387,24 +1462,49 @@ static void enterScope (tokenInfo *const parentToken,
 		{
 			case TOKEN_OPEN_CURLY:
 				enterScope (token, NULL, -1);
+				vStringClear (CurrentStatement.docblock);
 				break;
 
 			case TOKEN_KEYWORD:
 				switch (token->keyword)
 				{
-					case KEYWORD_class:		readNext = parseClassOrIface (token, K_CLASS);		break;
-					case KEYWORD_interface:	readNext = parseClassOrIface (token, K_INTERFACE);	break;
-					case KEYWORD_trait:		readNext = parseTrait (token);						break;
-					case KEYWORD_function:	readNext = parseFunction (token, NULL);				break;
-					case KEYWORD_const:		readNext = parseConstant (token);					break;
-					case KEYWORD_define:	readNext = parseDefine (token);						break;
+					case KEYWORD_class:
+						readNext = parseClassOrIface (token, K_CLASS);
+						vStringClear (CurrentStatement.docblock);
+						break;
+					case KEYWORD_interface:
+						readNext = parseClassOrIface (token, K_INTERFACE);
+						vStringClear (CurrentStatement.docblock);
+						break;
+					case KEYWORD_trait:
+						readNext = parseTrait (token);
+						vStringClear (CurrentStatement.docblock);
+						break;
+					case KEYWORD_function:
+						readNext = parseFunction (token, NULL);
+						vStringClear (CurrentStatement.docblock);
+						break;
+					case KEYWORD_const:
+						readNext = parseConstant (token);
+						vStringClear (CurrentStatement.docblock);
+						break;
+					case KEYWORD_define:
+						readNext = parseDefine (token);
+						vStringClear (CurrentStatement.docblock);
+						break;
 
-					case KEYWORD_namespace:	readNext = parseNamespace (token);	break;
+					case KEYWORD_namespace:
+						readNext = parseNamespace (token);
+						vStringClear (CurrentStatement.docblock);
+						break;
 
 					case KEYWORD_private:	CurrentStatement.access = ACCESS_PRIVATE;	break;
 					case KEYWORD_protected:	CurrentStatement.access = ACCESS_PROTECTED;	break;
 					case KEYWORD_public:	CurrentStatement.access = ACCESS_PUBLIC;	break;
-					case KEYWORD_var:		CurrentStatement.access = ACCESS_PUBLIC;	break;
+					case KEYWORD_var:
+						CurrentStatement.access = ACCESS_PUBLIC;
+						vStringClear (CurrentStatement.docblock);
+						break;
 
 					case KEYWORD_abstract:	CurrentStatement.impl = IMPL_ABSTRACT;		break;
 
@@ -1414,6 +1514,7 @@ static void enterScope (tokenInfo *const parentToken,
 
 			case TOKEN_VARIABLE:
 				readNext = parseVariable (token);
+				vStringClear (CurrentStatement.docblock);
 				break;
 
 			default: break;
@@ -1435,6 +1536,7 @@ static void findPhpTags (void)
 	InPhp = FALSE;
 	CurrentStatement.access = ACCESS_UNDEFINED;
 	CurrentStatement.impl = IMPL_UNDEFINED;
+	CurrentStatement.docblock = vStringNew ();
 	CurrentNamesapce = vStringNew ();
 
 	do

read.h

@@ -11,12 +11,6 @@
 #ifndef _READ_H
 #define _READ_H
 
-#if defined(FILE_WRITE) || defined(VAXC)
-# define CONST_FILE
-#else
-# define CONST_FILE const
-#endif
-
 /*
 *   INCLUDE FILES
 */
@@ -94,7 +88,7 @@ typedef struct sInputFile {
 /*
 *   GLOBAL VARIABLES
 */
-extern CONST_FILE inputFile File;
+extern inputFile File;
 
 /*
 *   FUNCTION PROTOTYPES