consoleDoc.cpp

Public Functions

ConsoleFunctionGroupBegin(ConsoleDoc , "Console self-documentation functions. These output psuedo C++ suitable <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> feeeding through Doxygen or another auto documentation tool." )

ConsoleFunctionGroupEnd(ConsoleDoc )

DefineConsoleFunction(dumpConsoleClasses , void , (bool dumpScript, bool dumpEngine) , (true, true) , "@brief Dumps all declared console classes <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> the <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">console.\n\n</a>" "@param dumpScript Optional parameter specifying whether or not classes defined in script should be <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">dumped.\n</a>" "@param dumpEngine Optional parameter specifying whether or not classes defined in the engine should be <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">dumped.\n</a>" "@ingroup Logging" )

DefineConsoleFunction(dumpConsoleFunctions , void , (bool dumpScript, bool dumpEngine) , (true, true) , "@brief Dumps all declared console functions <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> the <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">console.\n</a>" "@param dumpScript Optional parameter specifying whether or not functions defined in script should be <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">dumped.\n</a>" "@param dumpEngine Optional parameter specitying whether or not functions defined in the engine should be <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">dumped.\n</a>" "@ingroup Logging" )

printClassFooter()

printClassHeader(const char * usage, const char * className, const char * superClassName, const bool stub)

printClassMember(const bool isDeprec, const char * aType, const char * aName, const char * aDocs)

printClassMethod(const bool isVirtual, const char * retType, const char * methodName, const char * args, const char * usage)

printGroupEnd()

printGroupStart(const char * aName, const char * aDocs)

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#include "platform/platform.h"
 25#include "console/console.h"
 26
 27#include "console/ast.h"
 28#include "core/tAlgorithm.h"
 29
 30#include "core/strings/findMatch.h"
 31#include "console/consoleInternal.h"
 32#include "console/consoleObject.h"
 33#include "core/stream/fileStream.h"
 34#include "console/compiler.h"
 35#include "core/frameAllocator.h"
 36#include "console/engineAPI.h"
 37
 38//--- Information pertaining to this page... ------------------
 39/// @file
 40///
 41/// For specifics on using the consoleDoc functionality, see @ref console_autodoc
 42
 43ConsoleFunctionGroupBegin(ConsoleDoc, "Console self-documentation functions. These output psuedo C++ suitable for feeeding through Doxygen or another auto documentation tool.");
 44
 45DefineConsoleFunction( dumpConsoleClasses, void, (bool dumpScript, bool dumpEngine), ( true, true ),
 46            "@brief Dumps all declared console classes to the console.\n\n"
 47            "@param dumpScript Optional parameter specifying whether or not classes defined in script should be dumped.\n"
 48            "@param dumpEngine Optional parameter specifying whether or not classes defined in the engine should be dumped.\n"
 49         "@ingroup Logging")
 50{
 51   Namespace::dumpClasses( dumpScript, dumpEngine );
 52}
 53
 54DefineConsoleFunction(dumpConsoleFunctions, void, ( bool dumpScript, bool dumpEngine ), ( true, true ),
 55            "@brief Dumps all declared console functions to the console.\n"
 56            "@param dumpScript Optional parameter specifying whether or not functions defined in script should be dumped.\n"
 57            "@param dumpEngine Optional parameter specitying whether or not functions defined in the engine should be dumped.\n"
 58         "@ingroup Logging")
 59{
 60   Namespace::dumpFunctions( dumpScript, dumpEngine );
 61}
 62
 63ConsoleFunctionGroupEnd(ConsoleDoc);
 64
 65/// Helper table to convert type ids to human readable names.
 66const char *typeNames[] = 
 67{
 68      "Script",
 69      "string",
 70      "int",
 71      "float",
 72      "void",
 73      "bool",
 74      "",
 75      "",
 76      "unknown_overload"
 77};
 78
 79void printClassHeader(const char* usage, const char * className, const char * superClassName, const bool stub)
 80{
 81   if(stub) 
 82   {
 83      Con::printf("/// Stub class");
 84      Con::printf("/// ");
 85      Con::printf("/// @note This is a stub class to ensure a proper class hierarchy. No ");
 86      Con::printf("///       information was available for this class.");
 87   }
 88
 89   if( usage != NULL )
 90   {
 91      // Copy Usage Document
 92      S32 usageLen = dStrlen( usage );
 93      FrameTemp<char> usageStr( usageLen );
 94      dStrcpy( usageStr, usage );
 95
 96      // Print Header
 97      Con::printf( "/*!" );
 98
 99      // Print line by line, skipping the @field lines.
100      //
101      // fetch first line end
102      char *newLine = dStrchr( usageStr, '\n' );
103      char *usagePtr = usageStr;
104      do 
105      {
106         // Copy of one line
107         static char lineStr[2048] = {0};
108         // Keyword will hold the last keyword (word following '@' or '\') encountered.
109         static char keyword[8] = {0};
110
111         S32 lineLen = 0;
112
113         // If not the last line, increment pointer
114         if( newLine != NULL )
115         {
116            *newLine = '\0';
117            newLine ++;
118         }
119         
120         // Copy line and update usagePtr
121         dStrcpy( lineStr, usagePtr );
122         usagePtr = (newLine != NULL ) ? newLine : usagePtr;
123         lineLen = dStrlen( lineStr );
124
125         // Get the keyword. This is the first word after an '@' or '\'.
126         const char* tempkw = dStrchr( lineStr, '@' );
127         if( !tempkw )
128            tempkw = dStrchr( lineStr, '\\' );
129
130         // If we found a new keyword, set it, otherwise, keep using the
131         // most recently found.
132         if( tempkw )
133         {
134            dStrncpy( keyword, tempkw + 1, 5 );
135            keyword[5] = '\0';
136         }
137
138         // Print all fields that aren't associated with the 'field' keyword.
139         if( dStrcmp( keyword, "field" ) )
140            Con::printf( "%s", lineStr );    // print lineStr as an unformatted string (otherwise '%' characters in the string could cause problems)
141
142
143         // Fetch next line ending
144         newLine = dStrchr( usagePtr, '\n' );
145      } while( newLine != NULL );
146
147      // DocBlock Footer
148      Con::printf( " */" );
149
150   }
151
152   // Print out appropriate class header
153   if(superClassName)
154      Con::printf("class  %s : public %s {", className, superClassName ? superClassName : "");
155   else if(!className)
156      Con::printf("namespace Global {");
157   else
158      Con::printf("class  %s {", className);
159
160   if(className)
161      Con::printf("  public:");
162
163}
164
165void printClassMethod(const bool isVirtual, const char *retType, const char *methodName, const char* args, const char*usage)
166{
167   if(usage && usage[0] != ';' && usage[0] != 0)
168      Con::printf("   /*! %s */", usage);
169   Con::printf("   %s%s %s(%s) {}", isVirtual ? "virtual " : "", retType, methodName, args);
170}
171
172void printGroupStart(const char * aName, const char * aDocs)
173{
174   Con::printf("");
175   Con::printf("   /*! @name %s", aName);
176
177   if(aDocs)
178   {
179      Con::printf("   ");
180      Con::printf("   %s", aDocs);
181   }
182
183   Con::printf("   @{ */");
184
185   // Add a blank comment in order to make sure groups are parsed properly.
186   Con::printf("   /*! */");
187}
188
189void printClassMember(const bool isDeprec, const char * aType, const char * aName, const char * aDocs)
190{
191   Con::printf("   /*!");
192
193   if(aDocs)
194   {
195      Con::printf("   %s", aDocs);
196      Con::printf("   ");
197   }
198
199   if(isDeprec)
200      Con::printf("   @deprecated This member is deprecated, which means that its value is always undefined.");
201
202   Con::printf("    */");
203
204   Con::printf("   %s %s;", isDeprec ? "deprecated" : aType, aName);
205}
206
207void printGroupEnd()
208{
209   Con::printf("   /// @}");
210   Con::printf("");
211}
212
213void printClassFooter()
214{
215   Con::printf("};");
216   Con::printf("");
217}
218
219void Namespace::printNamespaceEntries(Namespace * g, bool dumpScript, bool dumpEngine )
220{
221   static bool inGroup = false;
222
223   // Go through all the entries.
224   // Iterate through the methods of the namespace...
225   for(Entry *ewalk = g->mEntryList; ewalk; ewalk = ewalk->mNext)
226   {
227      S32 eType = ewalk->mType;
228      const char * funcName = ewalk->mFunctionName;
229
230      if( ( eType == Entry::ConsoleFunctionType ) && !dumpScript )
231         continue;
232
233      if( ( eType != Entry::ConsoleFunctionType ) && !dumpEngine )
234         continue;
235
236      // If it's a function
237      if( eType >= Entry::ConsoleFunctionType )
238      {
239         printClassMethod(true, typeNames[eType], funcName, ewalk->getArgumentsString().c_str(),
240            ewalk->getDocString().c_str());
241      }
242      else if(ewalk->mType == Entry::GroupMarker)
243      {
244         if(!inGroup)
245            printGroupStart(ewalk->cb.mGroupName, ewalk->mUsage);
246         else 
247            printGroupEnd();
248
249         inGroup = !inGroup;
250      }
251      else if(ewalk->mType == Entry::ScriptCallbackType)
252      {
253         // It's a script callback - emit some sort of appropriate info.
254         Con::printf("      /*! %s */", ewalk->getDocString().c_str());
255         Con::printf("      %s;", ewalk->getPrototypeString().c_str());
256         Con::printf("");
257      }
258      else if(ewalk->mFunctionOffset)                 // If it's a builtin function...
259      {
260         String args = ewalk->mCode->getFunctionArgs(ewalk->mFunctionOffset);
261         printClassMethod(false, typeNames[ewalk->mType], ewalk->mFunctionName, args, "");
262      }
263      else
264      {
265         Con::printf("   // got an unknown thing?? %d", ewalk->mType );
266      }
267   }
268}
269
270void Namespace::dumpClasses( bool dumpScript, bool dumpEngine )
271{
272   VectorPtr<Namespace*> vec;
273   trashCache();
274   vec.reserve( 1024 );
275
276   // We use mHashSequence to mark if we have traversed...
277   // so mark all as zero to start.
278   for(Namespace *walk = mNamespaceList; walk; walk = walk->mNext)
279      walk->mHashSequence = 0;
280
281   for(Namespace *walk = mNamespaceList; walk; walk = walk->mNext)
282   {
283      VectorPtr<Namespace*> stack;
284      stack.reserve( 1024 );
285
286      // Get all the parents of this namespace... (and mark them as we go)
287      Namespace *parentWalk = walk;
288      while(parentWalk)
289      {
290         if(parentWalk->mHashSequence != 0)
291            break;
292         if(parentWalk->mPackage == 0)
293         {
294            parentWalk->mHashSequence = 1;   // Mark as traversed.
295            stack.push_back(parentWalk);
296         }
297         parentWalk = parentWalk->mParent;
298      }
299
300      // Load stack into our results vector.
301      while(stack.size())
302      {
303         vec.push_back(stack[stack.size() - 1]);
304         stack.pop_back();
305      }
306   }
307
308   // Go through previously discovered classes
309   U32 i;
310   for(i = 0; i < vec.size(); i++)
311   {
312      const char *className = vec[i]->mName;
313      const char *superClassName = vec[i]->mParent ? vec[i]->mParent->mName : NULL;
314
315      // Skip the global namespace, that gets dealt with in dumpFunctions
316      if(!className) continue;
317
318      // If we're just dumping script functions, then we don't want to dump
319      // a class that only contains script functions. So, we iterate over all
320      // the functions.
321      if( !dumpScript )
322      {
323         bool found = false;
324         for(Entry *ewalk = vec[i]->mEntryList; ewalk; ewalk = ewalk->mNext)
325         {
326            if( ewalk->mType != Entry::ConsoleFunctionType )
327            {
328               found = true;
329               break;
330            }
331         }
332
333         // If we don't have engine functions and the namespace name
334         // doesn't match the class name... then its a script class.
335         if ( !found && !vec[i]->isClass() )
336            continue;
337      }
338
339      // And we do the same for engine functions.
340      if( !dumpEngine )
341      {
342         bool found = false;
343         for(Entry *ewalk = vec[i]->mEntryList; ewalk; ewalk = ewalk->mNext)
344         {
345            if( ewalk->mType == Entry::ConsoleFunctionType )
346            {
347               found = true;
348               break;
349            }
350         }
351         if( !found )
352            continue;
353      }
354
355      // If we hit a class with no members and no classRep, do clever filtering.
356      if(vec[i]->mEntryList == NULL && vec[i]->mClassRep == NULL)
357      {
358         // Print out a short stub so we get a proper class hierarchy.
359         if(superClassName) { // Filter hack; we don't want non-inheriting classes...
360            printClassHeader( NULL, className,superClassName, true);
361            printClassFooter();
362         }
363         continue;
364      }
365
366      // Print the header for the class..
367      printClassHeader(vec[i]->mUsage, className, superClassName, false);
368
369      // Deal with entries.
370      printNamespaceEntries(vec[i], dumpScript, dumpEngine);
371
372      // Deal with the classRep (to get members)...
373      AbstractClassRep *rep = vec[i]->mClassRep;
374      AbstractClassRep::FieldList emptyList;
375      AbstractClassRep::FieldList *parentList = &emptyList;
376      AbstractClassRep::FieldList *fieldList = &emptyList;
377
378      // Since all fields are defined in the engine, if we're not dumping
379      // engine stuff, than we shouldn't dump the fields.
380      if(dumpEngine && rep)
381      {
382         // Get information about the parent's fields...
383         AbstractClassRep *parentRep = vec[i]->mParent ? vec[i]->mParent->mClassRep : NULL;
384         if(parentRep)
385            parentList = &(parentRep->mFieldList);
386
387         // Get information about our fields
388         fieldList = &(rep->mFieldList);
389
390         // Go through all our fields...
391         for(U32 j = 0; j < fieldList->size(); j++)
392         {
393            switch((*fieldList)[j].type)
394            {
395            case AbstractClassRep::StartArrayFieldType:
396            case AbstractClassRep::EndArrayFieldType:
397               break;
398            case AbstractClassRep::StartGroupFieldType:
399               printGroupStart((*fieldList)[j].pGroupname, (*fieldList)[j].pFieldDocs);
400               break;
401            case AbstractClassRep::EndGroupFieldType:
402               printGroupEnd();
403               break;
404            default:
405            case AbstractClassRep::DeprecatedFieldType:
406               {
407                  // Skip over fields that are already defined in
408                  // our parent class.
409                  if ( parentRep && parentRep->findField( (*fieldList)[j].pFieldname ) )
410                     continue;
411
412                  bool isDeprecated = ((*fieldList)[j].type == AbstractClassRep::DeprecatedFieldType);
413
414                  if(isDeprecated)
415                  {
416                     printClassMember(
417                        true,
418                        "<deprecated>",
419                        (*fieldList)[j].pFieldname,
420                        (*fieldList)[j].pFieldDocs
421                        );
422                  }
423                  else
424                  {
425                     ConsoleBaseType *cbt = ConsoleBaseType::getType((*fieldList)[j].type);
426
427                     printClassMember(
428                        false,
429                        cbt ? cbt->getTypeClassName() : "<unknown>",
430                        (*fieldList)[j].pFieldname,
431                        (*fieldList)[j].pFieldDocs
432                        );
433                  }
434               }
435            }
436         }
437      }
438
439      if( dumpScript )
440      {
441         // Print out fields defined in script docs for this namespace.
442         // These fields are specified by the 'field' keyword in the usage
443         // string.
444
445         // The field type and name.
446         char fieldName[256];
447         char fieldDoc[1024];
448
449         // Usage string iterator.
450         const char* field = vec[i]->mUsage;
451
452         while( field )
453         {
454            // Find the first field keyword.
455            const char* tempField = dStrstr( field, "@field" );
456            if( !tempField )
457               tempField = dStrstr( field, "\\field" );
458
459            field = tempField;
460
461            if( !field )
462               break;
463
464            // Move to the field name.
465            field += 7;
466
467            // Copy the field type and name. These should both be followed by a
468            // space so only in this case will we actually store it.
469            S32 spaceCount = 0;
470            S32 index = 0;
471            bool valid = false;
472            while( field && ( *field != '\n' ) )
473            {
474               if( index >= 255 )
475                  break;
476
477               if( *field == ' ' )
478                  spaceCount++;
479
480               if( spaceCount == 2 )
481               {
482                  valid = true;
483                  break;
484               }
485
486               fieldName[index++] = *field;
487               field++;
488            }
489
490            if( !valid )
491               continue;
492
493            fieldName[index] = '\0';
494
495            // Now copy from field to the next keyword.
496            const char* nextKeyword = dStrchr( field, '@' );
497            if( !nextKeyword )
498               nextKeyword = dStrchr( field, '\\' );
499
500            // Grab the length of the doc string.
501            S32 docLen = dStrlen( field );
502            if( nextKeyword )
503               docLen = nextKeyword - field;
504
505            // Make sure it will fit in the buffer.
506            if( docLen > 1023 )
507               docLen = 1023;
508
509            // Copy.
510            dStrncpy( fieldDoc, field, docLen );
511            fieldDoc[docLen] = '\0';
512            field += docLen;
513
514            // Print
515            Con::printf( "   /*!" );
516            Con::printf( "   %s", fieldDoc );
517            Con::printf( "    */" );
518            Con::printf( "   %s;", fieldName );
519         }
520      }
521
522      // Close the class/namespace.
523      printClassFooter();
524   }
525}
526
527void Namespace::dumpFunctions( bool dumpScript, bool dumpEngine )
528{
529   // Get the global namespace.
530   Namespace* g = find(NULL); //->mParent;
531
532   printClassHeader(NULL, NULL,NULL, false);
533
534   while(g) 
535   {
536      printNamespaceEntries(g, dumpScript, dumpEngine );
537      g = g->mParent;
538   }
539
540   printClassFooter();
541}
542