/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) 2007 INRIA

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 *

 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>

 */

/**

 * \file

 * \ingroup utils

 * Generate documentation from the TypeId database.

 */

#include <iostream>

#include <algorithm>

#include <map>

#include <climits>    // CHAR_BIT

#include "ns3/command-line.h"

#include "ns3/config.h"

#include "ns3/global-value.h"

#include "ns3/log.h"

#include "ns3/object-vector.h"

#include "ns3/object.h"

#include "ns3/pointer.h"

#include "ns3/string.h"

#include "ns3/node-container.h"

#include "ns3/simple-channel.h"

using namespace ns3;

NS_LOG_COMPONENT_DEFINE ("PrintIntrospectedDoxygen");

namespace

{

  std::string anchor;              ///< hyperlink anchor

  std::string argument;            ///< function argument

  std::string boldStart;           ///< start of bold span

  std::string boldStop;            ///< end of bold span

  std::string breakBoth;           ///< linebreak

  std::string breakHtmlOnly;       ///< linebreak for html output only

  std::string breakTextOnly;       ///< linebreak for text output only

  std::string brief;               ///< brief tag

  std::string classStart;          ///< start of a class

  std::string classStop;           ///< end of a class

  std::string codeWord;            ///< format next word as source code

  std::string commentStart;        ///< start of code comment

  std::string commentStop;         ///< end of code comment

  std::string copyDoc;             ///< copy (or refer) to docs elsewhere

  std::string flagSpanStart;       ///< start of Attribute flag value

  std::string flagSpanStop;        ///< end of Attribute flag value

  std::string functionStart;       ///< start of a method/function

  std::string functionStop;        ///< end of a method/function

  std::string headingStart;        ///< start of section heading (h3)

  std::string headingStop;         ///< end of section heading (h3)

  std::string indentHtmlOnly;      ///< small indent

  std::string listLineStart;       ///< start unordered list item

  std::string listLineStop;        ///< end unordered list item

  std::string listStart;           ///< start unordered list

  std::string listStop;            ///< end unordered list

  std::string page;                ///< start a separate page

  std::string reference;           ///< reference tag

  std::string returns;             ///< the return value

  std::string sectionStart;        ///< start of a section or group

  std::string seeAlso;             ///< Reference to other docs

  std::string subSectionStart;     ///< start a new subsection

  std::string templateArgument;    ///< template argument

  std::string templArgExplicit;    ///< template argument required

  std::string templArgDeduced;     ///< template argument deduced from function

  std::string variable;            ///< variable or class member

} // anonymous namespace

/**

 * Initialize the markup strings, for either doxygen or text.

 *

 * \param [in] outputText true for text output, false for doxygen output.

 */

void

SetMarkup (bool outputText)

{

  NS_LOG_FUNCTION (outputText);

  if (outputText)

    {

      anchor                       = "";

      argument                     = "  Arg: ";

      boldStart                    = "";

      boldStop                     = "";

      breakBoth                    = "\n";

      breakHtmlOnly                = "";

      breakTextOnly                = "\n";

      brief                        = "";

      classStart                   = "";

      classStop                    = "\n\n";

      codeWord                     = " ";

      commentStart                 = "===============================================================\n";

      commentStop                  = "";

      copyDoc                      = "  See: ";

      flagSpanStart                = "";

      flagSpanStop                 = "";

      functionStart                = "";

      functionStop                 = "\n\n";

      headingStart                 = "";

      headingStop                  = "";

      indentHtmlOnly               = "";

      page                         = "Page ";

      listStart                    = "";

      listStop                     = "";

      listLineStart                = "    * ";

      listLineStop                 = "";

      reference                    = " ";

      returns                      = "  Returns: ";

      sectionStart                 = "Section ";

      seeAlso                      = "  See: ";

      subSectionStart              = "Subsection ";

      templateArgument             = "Template Arg: ";

      templArgDeduced              = "[deduced]  ";

      templArgExplicit             = "[explicit] ";

      variable                     = "Variable: ";

    }

  else

    {

      anchor                       = "\\anchor ";

      argument                     = "\\param ";

      boldStart                    = "<b>";

      boldStop                     = "</b>";

      breakBoth                    = "<br>";

      breakHtmlOnly                = "<br>";

      breakTextOnly                = "";

      brief                        = "\\brief ";

      classStart                   = "\\class ";

      classStop                    = "";

      codeWord                     = "\\p ";

      commentStart                 = "/*!\n";

      commentStop                  = "*/\n";

      copyDoc                      = "\\copydoc ";

      flagSpanStart                = "<span class=\"mlabel\">";

      flagSpanStop                 = "</span>";

      functionStart                = "\\fn ";

      functionStop                 = "";

      headingStart                 = "<h3>";

      headingStop                  = "</h3>";

      indentHtmlOnly               = "  ";

      page                         = "\\page ";

      listStart                    = "<ul>";

      listStop                     = "</ul>";

      listLineStart                = "<li>";

      listLineStop                 = "</li>";

      reference                    = " \\ref ";

      returns                      = "\\returns ";

      sectionStart                 = "\\ingroup ";

      seeAlso                      = "\\see ";

      subSectionStart              = "\\addtogroup ";

      templateArgument             = "\\tparam ";

      templArgDeduced              = "\\deduced ";

      templArgExplicit             = "\\explicit ";

      variable                     = "\\var ";

    }

}  // SetMarkup ()

/***************************************************************

 *        Docs for a single TypeId

 ***************************************************************/

/**

 * Print direct Attributes for this TypeId.

 *

 * Only attributes defined directly by this TypeId will be printed.

 *

 * \param [in,out] os The output stream.

 * \param [in] tid The TypeId to print.

 */

void

PrintAttributesTid (std::ostream &os, const TypeId tid)

{

  NS_LOG_FUNCTION (tid);

  os << listStart << std::endl;

  for (uint32_t j = 0; j < tid.GetAttributeN (); j++)

    {

      struct TypeId::AttributeInformation info = tid.GetAttribute(j);

      os << listLineStart

	 <<   boldStart << info.name << boldStop << ": "

	 <<   info.help

	 <<   std::endl;

      os <<   "  "

	 <<   listStart << std::endl;

      os <<     "    "

	 <<     listLineStart

	 <<       "Set with class: " << reference

	 <<       info.checker->GetValueTypeName ()

	 <<     listLineStop

	 << std::endl;

      if (info.checker->HasUnderlyingTypeInformation ())

	{

	  os << "    "

	     << listLineStart

	     <<   "Underlying type: ";

          std::string valType = info.checker->GetValueTypeName ();

          std::string underType = info.checker->GetUnderlyingTypeInformation ();

	  if ((valType   != "ns3::EnumValue") && (underType != "std::string"))

	    {

	      // Indirect cases to handle

	      bool handled = false;

	      if (valType == "ns3::PointerValue")

		{

		  const PointerChecker *ptrChecker =

		    dynamic_cast<const PointerChecker *> (PeekPointer (info.checker));

		  if (ptrChecker != 0)

		    {

		      os << reference << "ns3::Ptr" << "< "

			 << reference << ptrChecker->GetPointeeTypeId ().GetName ()

			 << ">";

		      handled = true;

		    }

		}

	      else if (valType == "ns3::ObjectPtrContainerValue")

		{

		  const ObjectPtrContainerChecker * ptrChecker =

		    dynamic_cast<const ObjectPtrContainerChecker *> (PeekPointer (info.checker));

		  if (ptrChecker != 0)

		    {

		      os << reference << "ns3::Ptr" << "< "

			 << reference << ptrChecker->GetItemTypeId ().GetName ()

			 << ">";

		      handled = true;

		    }

		}

              // Helper to match first part of string

              class StringBeginMatcher

              {

              public:

                StringBeginMatcher (const std::string s)

                  : m_string (s) { };

                bool operator () (const std::string t)

                {

                  std::size_t pos = m_string.find (t);

                  return pos == 0;

                };

              private:

                std::string m_string;

              };

              StringBeginMatcher match (underType);

              if ( match ("bool")     || match ("double")   ||

                   match ("int8_t")   || match ("uint8_t")  ||

                   match ("int16_t")  || match ("uint16_t") ||

                   match ("int32_t")  || match ("uint32_t") ||

                   match ("int64_t")  || match ("uint64_t")

                   )

                {

                  os << underType;

                  handled = true;

                }

	      if (! handled)

		{

		  os << reference << underType;

		}

	    }

	  os << listLineStop << std::endl;

	}

      if (info.flags & TypeId::ATTR_CONSTRUCT && info.accessor->HasSetter ())

	{

	  os << "    "

	     << listLineStart

	     <<   "Initial value: "

	     <<   info.initialValue->SerializeToString (info.checker)

	     << listLineStop

	     << std::endl;

	}

      os << "    " << listLineStart << "Flags: ";

      if (info.flags & TypeId::ATTR_CONSTRUCT && info.accessor->HasSetter ())

	{

	  os << flagSpanStart << "construct " << flagSpanStop;

	}

      if (info.flags & TypeId::ATTR_SET && info.accessor->HasSetter ())

	{

	  os << flagSpanStart << "write " << flagSpanStop;

	}

      if (info.flags & TypeId::ATTR_GET && info.accessor->HasGetter ())

	{

	  os << flagSpanStart << "read " << flagSpanStop;

	}

      os << listLineStop << std::endl;

      os << "  "

	 << listStop

	 << " " << std::endl;

    }

  os << listStop << std::endl;

}  // PrintAttributesTid ()

/**

 * Print the Attributes block for tid,

 * including Attributes declared in base classes.

 *

 * All Attributes of this TypeId will be printed,

 * including those defined in parent classes.

 *

 * \param [in,out] os The output stream.

 * \param [in] tid The TypeId to print.

 */

void

PrintAttributes (std::ostream & os, const TypeId tid)

{

  NS_LOG_FUNCTION (tid);

  if (tid.GetAttributeN () == 0)

    {

      os << "No Attributes are defined for this type."

	 << breakBoth

	 << std::endl;

    }

  else

    {

      os << headingStart

	 <<   "Attributes"

	 << headingStop

	 << std::endl;

      PrintAttributesTid (os, tid);

    }

  // Attributes from base classes

  TypeId tmp = tid.GetParent ();

  while (tmp.GetParent () != tmp)

    {

      if (tmp.GetAttributeN () != 0)

	{

	  os << headingStart

	     <<   "Attributes defined in parent class "

	     <<   tmp.GetName ()

	     << headingStop

	     << std::endl;

	  PrintAttributesTid (os, tmp);

	}

      tmp = tmp.GetParent ();

    }  // Attributes

} // PrintAttributes ()

/**

 * Print direct Trace sources for this TypeId.

 *

 * Only Trace sources defined directly by this TypeId will be printed.

 *

 * \param [in,out] os The output stream.

 * \param [in] tid The TypeId to print.

 */

void

PrintTraceSourcesTid (std::ostream & os, const TypeId tid)

{

  NS_LOG_FUNCTION (tid);

  os << listStart << std::endl;

  for (uint32_t i = 0; i < tid.GetTraceSourceN (); ++i)

    {

      struct TypeId::TraceSourceInformation info = tid.GetTraceSource (i);

      os << listLineStart

	 <<   boldStart << info.name << boldStop << ": "

	 <<   info.help << breakBoth

	//    '%' prevents doxygen from linking to the Callback class...

	 <<   "%Callback signature: " 

	 <<   info.callback

	 <<   std::endl;

      os << listLineStop << std::endl;

    }

  os << listStop << std::endl;

}  // PrintTraceSourcesTid ()

/**

 * Print the Trace sources block for tid,

 * including Trace sources declared in base classes.

 *

 * All Trace sources of this TypeId will be printed,

 * including those defined in parent classes.

 *

 * \param [in,out] os The output stream.

 * \param [in] tid The TypeId to print.

 */

void

PrintTraceSources (std::ostream & os, const TypeId tid)

{

  NS_LOG_FUNCTION (tid);

  if (tid.GetTraceSourceN () == 0)

    {

      os << "No TraceSources are defined for this type."

	 << breakBoth

	 << std::endl;

    }

  else

    {

      os << headingStart

	 <<   "TraceSources"

	 << headingStop  << std::endl;

      PrintTraceSourcesTid (os, tid);

    }

  // Trace sources from base classes

  TypeId tmp = tid.GetParent ();

  while (tmp.GetParent () != tmp)

    {

      if (tmp.GetTraceSourceN () != 0)

	{

	  os << headingStart

	     << "TraceSources defined in parent class "

	     << tmp.GetName ()

	     << headingStop << std::endl;

	  PrintTraceSourcesTid (os, tmp);

	}

      tmp = tmp.GetParent ();

    }

}  // PrintTraceSources ()

/**

 * Print the size of the type represented by this tid.

 *

 * \param [in,out] os The output stream.

 * \param [in] tid The TypeId to print.

 */

void PrintSize (std::ostream & os, const TypeId tid)

{

  NS_LOG_FUNCTION (tid);

  NS_ASSERT_MSG (CHAR_BIT != 0, "CHAR_BIT is zero");

  std::size_t arch = (sizeof (void *) * CHAR_BIT);

  os << boldStart << "Size" << boldStop

     << " of this type is " << tid.GetSize ()

     << " bytes (on a " << arch << "-bit architecture)."

     << std::endl;

}  // PrintSize ()

/***************************************************************

 *        Lists of All things

 ***************************************************************/

/**

 * Print the list of all Attributes.

 *

 * \param [in,out] os The output stream.

 */

void

PrintAllAttributes (std::ostream & os)

{

  NS_LOG_FUNCTION_NOARGS ();

  os << commentStart << page << "AttributeList All Attributes\n"

     << std::endl;

  os << "This is a list of all" << reference << "attribute by class.  "

     << "For more information see the" << reference << "attribute "

     << "section of this API documentation and the Attributes sections "

     << "in the Tutorial and Manual.\n"

     << std::endl;

  for (uint32_t i = 0; i < TypeId::GetRegisteredN (); ++i)

    {

      TypeId tid = TypeId::GetRegistered (i);

      if (tid.GetAttributeN () == 0 ||

	  tid.MustHideFromDocumentation ())

	{

	  continue;

	}

      os << boldStart << tid.GetName () << boldStop << breakHtmlOnly

	 << std::endl;

      os << listStart << std::endl;

      for (uint32_t j = 0; j < tid.GetAttributeN (); ++j)