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