autodoc/source/display/html/hd_docu.cxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: hd_docu.cxx,v $
  10  * $Revision: 1.12 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #include <precomp.h>
  32 #include "hd_docu.hxx"
  33
  34
  35 // NOT FULLY DEFINED SERVICES
  36 #include <ary/cpp/c_gate.hxx>
  37 #include <ary/cpp/c_namesp.hxx>
  38 #include <ary/cpp/c_class.hxx>
  39 #include <ary/cpp/c_enum.hxx>
  40 #include <ary/cpp/c_tydef.hxx>
  41 #include <ary/cpp/c_funct.hxx>
  42 #include <ary/cpp/c_vari.hxx>
  43 #include <ary/cpp/c_enuval.hxx>
  44 #include <ary/doc/d_oldcppdocu.hxx>
  45 #include <ary/info/all_tags.hxx>
  46 #include <ary/info/all_dts.hxx>
  47 #include <adc_cl.hxx>
  48 #include "html_kit.hxx"
  49 #include "opageenv.hxx"
  50
  51
  52
  53 using namespace ary::info;
  54 using namespace csi;
  55
  56 using html::DefList;
  57 using html::DefListTerm;
  58 using html::DefListDefinition;
  59 using html::Headline;
  60 using html::Link;
  61
  62
  63 const char *
  64 C_sTagHeadlines[ ary::info::C_eAtTag_NrOfClasses ] =
  65     {
  66         "ATTENTION!",   "Author",       "Changes",      "Collaborators",
  67                                                                         "Contact",  // Contact may be unused
  68         "Copyright",    "Deprecated",   "Description",  "Date of Documentation",
  69                                                                         "How to Derive from this Class",
  70         "Heap object - owner is responsible for deletion.",
  71                         "Important Instances",
  72                                         "Interface Only",
  73                                                         "Invariant",    "Lifecycle",
  74         "Multiplicity", "On Error",     "Persistency",  "Postcondition",
  75                                                                         "Precondition",
  76         "Responsibilities",
  77                         "Return",       "Summary",      "Todos",        "Version",
  78         "Base Classes", "Exceptions",   "Implements",   "Keywords",     "Parameters",
  79         "See Also",     "Template Parameters",
  80                                         "",             "Since "
  81     };
  82
  83
  84
  85 Docu_Display::Docu_Display( OuputPage_Environment & io_rEnv )
  86     :   HtmlDisplay_Impl(io_rEnv),
  87         bUseHtmlInDocuTokens(false),
  88         pCurClassOverwrite(0)
  89 {
  90 }
  91
  92 Docu_Display::~Docu_Display()
  93 {
  94 }
  95
  96 void
  97 Docu_Display::Assign_Out( csi::xml::Element & o_rOut )
  98 {
  99     Easy().Enter(o_rOut);
 100 }
 101
 102 void
 103 Docu_Display::Unassign_Out()
 104 {
 105     Easy().Leave();
 106 }
 107
 108 void
 109 Docu_Display::do_Process( const ary::cpp::Namespace & i_rData )
 110 {
 111     Process(i_rData.Docu());
 112 }
 113
 114 void
 115 Docu_Display::do_Process( const ary::cpp::Class & i_rData )
 116 {
 117     pCurClassOverwrite = &i_rData;
 118     Process(i_rData.Docu());
 119     pCurClassOverwrite = 0;
 120 }
 121
 122 void
 123 Docu_Display::do_Process( const ary::cpp::Enum & i_rData )
 124 {
 125     Process(i_rData.Docu());
 126 }
 127
 128 void
 129 Docu_Display::do_Process( const ary::cpp::Typedef & i_rData )
 130 {
 131     Process(i_rData.Docu());
 132 }
 133
 134 void
 135 Docu_Display::do_Process( const ary::cpp::Function & i_rData )
 136 {
 137     Process(i_rData.Docu());
 138 }
 139
 140 void
 141 Docu_Display::do_Process( const ary::cpp::Variable & i_rData )
 142 {
 143     Process(i_rData.Docu());
 144 }
 145
 146
 147
 148 // --------------       Interface ary::info::DocuDisplay  ------------------ //
 149
 150
 151 void
 152 Docu_Display::do_Process(const ary::doc::Documentation & i_rData)
 153 {
 154     if (i_rData.Data() == 0)
 155         return;
 156
 157     const ary::doc::OldCppDocu *
 158         docdata = dynamic_cast< const ary::doc::OldCppDocu* >(i_rData.Data());
 159     csv_assert(docdata != 0);
 160
 161     Start_DocuBlock();
 162
 163     if ( docdata->IsObsolete() )
 164     {
 165         CurOut()
 166             >> *new html::DefListTerm
 167                 >> *new html::Strong
 168                     << "D E P R E C A T E D";
 169
 170     }
 171
 172     ary::doc::OldCppDocu::TagList::const_iterator
 173         itEnd = docdata->Tags().end();
 174     for ( ary::doc::OldCppDocu::TagList::const_iterator it = docdata->Tags().begin();
 175           it != itEnd;
 176           ++it )
 177     {
 178          (*it)->StoreAt( *this );
 179     }
 180
 181     Finish_DocuBlock();
 182 }
 183
 184 void
 185 Docu_Display::Display_StdTag( const StdTag & i_rData )
 186 {
 187     csv_assert( uintt(i_rData.Std_Id()) < uintt(ary::info::C_eAtTag_NrOfClasses) );
 188
 189     const ary::info::DocuText::TokenList &
 190         rText = i_rData.CText().Tokens();
 191     typedef ary::info::DocuText::TokenList::const_iterator TokenIterator;
 192
 193     if ( rText.empty() )
 194         return;
 195     else if ( rText.size() < 3 )
 196     {
 197         bool bIsWhite = true;
 198         for ( TokenIterator it = rText.begin();
 199               it != rText.end();
 200               ++it )
 201         {
 202             if (bIsWhite)
 203                 bIsWhite = (*it)->IsWhite();
 204         }
 205         if (bIsWhite)
 206             return;
 207     }
 208
 209     Write_TagTitle( C_sTagHeadlines[i_rData.Std_Id()] );
 210     Write_TagContents( i_rData.CText() );
 211 }
 212
 213 void
 214 Docu_Display::Display_BaseTag( const BaseTag & )
 215 {
 216 }
 217
 218 void
 219 Docu_Display::Display_ExceptionTag( const ExceptionTag & )
 220 {
 221 }
 222
 223 void
 224 Docu_Display::Display_ImplementsTag( const ImplementsTag & )
 225 {
 226 }
 227
 228 void
 229 Docu_Display::Display_KeywordTag( const KeywordTag & )
 230 {
 231 }
 232
 233 void
 234 Docu_Display::Display_ParameterTag( const ParameterTag & i_rData )
 235 {
 236     Write_TagTitle( "Parameters" );
 237
 238     adcdisp::ExplanationTable
 239         aParams( CurOut() >> *new DefListDefinition );
 240
 241     for ( const ParameterTag * pParam = &i_rData;
 242           pParam != 0;
 243           pParam = pParam->GetNext() )   // KORR_FUTURE
 244     {
 245         aParams.AddEntry( pParam->ParamName().c_str() );
 246
 247         Easy().Enter( aParams.Def() );
 248         Write_Text( pParam->CText() );
 249         Easy().Leave();
 250     }   // end for
 251 }
 252
 253 void
 254 Docu_Display::Display_SeeTag( const SeeTag & i_rData )
 255 {
 256     Write_TagTitle( "See Also" );
 257
 258     DefListDefinition * dpDef = new DefListDefinition;
 259     CurOut() << dpDef;
 260     Easy().Enter(*dpDef);
 261
 262     for ( std::vector< ary::QualifiedName >::const_iterator
 263             it = i_rData.References().begin();
 264           it != i_rData.References().end();
 265           ++it )
 266     {
 267         Write_LinkableText( (*it) );
 268         CurOut() << new html::LineBreak;
 269     }
 270
 271     Easy().Leave();
 272 }
 273
 274 void
 275 Docu_Display::Display_TemplateTag( const TemplateTag & i_rData )
 276 {
 277     Write_TagTitle( "Template Parameters" );
 278
 279     adcdisp::ExplanationTable
 280         aTplParams( CurOut() >> *new DefListDefinition );
 281
 282     for ( const TemplateTag * pTplParam = &i_rData;
 283           pTplParam != 0;
 284           pTplParam = pTplParam->GetNext() )
 285     {
 286         aTplParams.AddEntry( pTplParam->TplParamName().c_str() );
 287
 288         Easy().Enter( aTplParams.Def() );
 289         Write_Text( pTplParam->CText() );
 290         Easy().Leave();
 291     }   // end for
 292 }
 293
 294 void
 295 Docu_Display::Display_LabelTag( const LabelTag & )
 296 {
 297 }
 298
 299 void
 300 Docu_Display::Display_SinceTag( const ary::info::SinceTag & i_rData )
 301 {
 302     if ( i_rData.Version().empty() )
 303     {
 304          return;
 305     }
 306
 307     // Transform the value of the @since tag into the text to be displayed.
 308     String sDisplay;
 309     if ( autodoc::CommandLine::Get_().DoesTransform_SinceTag() )
 310     {
 311         sDisplay = autodoc::CommandLine::Get_()
 312                         .DisplayOf_SinceTagValue( i_rData.Version() );
 313     }
 314     else
 315     {
 316         sDisplay = i_rData.Version();
 317     }
 318
 319     if (sDisplay.empty())
 320         return;
 321
 322     Write_TagTitle( "Since " );
 323
 324     DefListDefinition * dpDef = new DefListDefinition;
 325     CurOut() << dpDef;
 326
 327     Easy().Enter(*dpDef);
 328     CurOut() << sDisplay;
 329     Easy().Leave();
 330 }
 331
 332 void
 333 Docu_Display::Display_DT_Text( const DT_Text & i_rData )
 334 {
 335     Write_TextToken(  i_rData.Text() );
 336 }
 337
 338 void
 339 Docu_Display::Display_DT_MaybeLink( const DT_MaybeLink & i_rData )
 340 {
 341     // KORR_FUTURE
 342     Write_TextToken(  i_rData.Text() );
 343 }
 344
 345 void
 346 Docu_Display::Display_DT_Whitespace( const DT_Whitespace & i_rData )
 347 {
 348     static char sSpace[300] =
 349         "                                         "
 350         "                                         "
 351         "                                         "
 352         "                                         "
 353         "                                         "
 354         "                                        ";
 355     UINT8 nLength = i_rData.Length();
 356     sSpace[nLength] = NULCH;
 357     CurOut() << sSpace;
 358     sSpace[nLength] = ' ';
 359 }
 360
 361 void
 362 Docu_Display::Display_DT_Eol( const DT_Eol & )
 363 {
 364     CurOut() << new html::Sbr;
 365 }
 366
 367 void
 368 Docu_Display::Display_DT_Xml( const ary::info::DT_Xml & i_rData )
 369 {
 370     CurOut() << new xml::XmlCode( i_rData.Text() );
 371 }
 372
 373 const ary::cpp::Gate *
 374 Docu_Display::inq_Get_ReFinder() const
 375 {
 376     return &Env().Gate();
 377 }
 378
 379 void
 380 Docu_Display::Start_DocuBlock()
 381 {
 382     DYN DefList * dpDefList = new DefList;
 383     CurOut() << dpDefList;
 384     Easy().Enter( *dpDefList );
 385 }
 386
 387 void
 388 Docu_Display::Finish_DocuBlock()
 389 {
 390     Easy().Leave();
 391 }
 392
 393 void
 394 Docu_Display::Write_TagTitle( const char *        i_sText,
 395                               const char *        )
 396 {
 397     if ( strcmp(i_sText,"ATTENTION!") == 0 )
 398     {
 399         CurOut()
 400             >> *new html::DefListTerm
 401                 << new html::ClassAttr("attention")
 402                 << i_sText;
 403     }
 404     else
 405     {
 406         CurOut()
 407             >> *new html::DefListTerm
 408                 << i_sText;
 409     }
 410 }
 411
 412 void
 413 Docu_Display::Write_TagContents( const DocuText & i_rDocuText )
 414 {
 415     DefListDefinition * dpDef = new DefListDefinition;
 416     CurOut() << dpDef;
 417
 418     Easy().Enter(*dpDef);
 419     Write_Text(i_rDocuText);
 420     Easy().Leave();
 421 }
 422
 423 void
 424 Docu_Display::Write_Text( const ary::info::DocuText & i_rDocuText )
 425 {
 426     if ( i_rDocuText.IsNoHtml() )
 427     {
 428         CurOut()
 429             << new xml::XmlCode("<pre>");
 430         bUseHtmlInDocuTokens = false;
 431     }
 432     else
 433     {
 434          bUseHtmlInDocuTokens = true;
 435     }
 436     i_rDocuText.StoreAt( *this );
 437     if ( i_rDocuText.IsNoHtml() )
 438     {
 439         CurOut()
 440             << new xml::XmlCode("</pre>");
 441     }
 442 }
 443
 444 void
 445 Docu_Display::Write_TextToken( const String & i_sText )
 446 {
 447      if ( bUseHtmlInDocuTokens )
 448         CurOut() << new xml::XmlCode(i_sText);
 449     else
 450         CurOut() << i_sText;
 451 }
 452
 453 void
 454 Docu_Display::Write_LinkableText( const ary::QualifiedName & i_sQuName )
 455 {
 456     const ary::cpp::CodeEntity *
 457         pCe = FindUnambiguousCe( Env(), i_sQuName, pCurClassOverwrite );
 458     if ( pCe != 0 )
 459     {
 460         csi::xml::Element *
 461             pLink = new csi::html::Link( Link2Ce(Env(), *pCe) );
 462         CurOut() << pLink;
 463         Easy().Enter(*pLink);
 464         Write_QualifiedName(i_sQuName);
 465         Easy().Leave();
 466     }
 467     else
 468     {
 469         Write_QualifiedName(i_sQuName);
 470     }
 471     CurOut() << " ";
 472 }
 473
 474 void
 475 Docu_Display::Write_QualifiedName( const ary::QualifiedName & i_sQuName )
 476 {
 477     if ( i_sQuName.IsAbsolute() )
 478         CurOut() << "::";
 479     for ( ary::QualifiedName::namespace_iterator it = i_sQuName.first_namespace();
 480           it != i_sQuName.end_namespace();
 481           ++it )
 482     {
 483         CurOut() <<  (*it) << "::";
 484     }
 485     CurOut() << i_sQuName.LocalName();
 486     if ( i_sQuName.IsFunction() )
 487         CurOut() << "()";
 488 }
 489