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
Docu_Display(OuputPage_Environment & io_rEnv)76 Docu_Display::Docu_Display( OuputPage_Environment & io_rEnv )
77 : HtmlDisplay_Impl(io_rEnv),
78 bUseHtmlInDocuTokens(false),
79 pCurClassOverwrite(0)
80 {
81 }
82
~Docu_Display()83 Docu_Display::~Docu_Display()
84 {
85 }
86
87 void
Assign_Out(csi::xml::Element & o_rOut)88 Docu_Display::Assign_Out( csi::xml::Element & o_rOut )
89 {
90 Easy().Enter(o_rOut);
91 }
92
93 void
Unassign_Out()94 Docu_Display::Unassign_Out()
95 {
96 Easy().Leave();
97 }
98
99 void
do_Process(const ary::cpp::Namespace & i_rData)100 Docu_Display::do_Process( const ary::cpp::Namespace & i_rData )
101 {
102 Process(i_rData.Docu());
103 }
104
105 void
do_Process(const ary::cpp::Class & i_rData)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
do_Process(const ary::cpp::Enum & i_rData)114 Docu_Display::do_Process( const ary::cpp::Enum & i_rData )
115 {
116 Process(i_rData.Docu());
117 }
118
119 void
do_Process(const ary::cpp::Typedef & i_rData)120 Docu_Display::do_Process( const ary::cpp::Typedef & i_rData )
121 {
122 Process(i_rData.Docu());
123 }
124
125 void
do_Process(const ary::cpp::Function & i_rData)126 Docu_Display::do_Process( const ary::cpp::Function & i_rData )
127 {
128 Process(i_rData.Docu());
129 }
130
131 void
do_Process(const ary::cpp::Variable & i_rData)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
do_Process(const ary::doc::Documentation & i_rData)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
Display_StdTag(const StdTag & i_rData)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
Display_BaseTag(const BaseTag &)205 Docu_Display::Display_BaseTag( const BaseTag & )
206 {
207 }
208
209 void
Display_ExceptionTag(const ExceptionTag &)210 Docu_Display::Display_ExceptionTag( const ExceptionTag & )
211 {
212 }
213
214 void
Display_ImplementsTag(const ImplementsTag &)215 Docu_Display::Display_ImplementsTag( const ImplementsTag & )
216 {
217 }
218
219 void
Display_KeywordTag(const KeywordTag &)220 Docu_Display::Display_KeywordTag( const KeywordTag & )
221 {
222 }
223
224 void
Display_ParameterTag(const ParameterTag & i_rData)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
Display_SeeTag(const SeeTag & i_rData)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
Display_TemplateTag(const TemplateTag & i_rData)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
Display_LabelTag(const LabelTag &)286 Docu_Display::Display_LabelTag( const LabelTag & )
287 {
288 }
289
290 void
Display_SinceTag(const ary::info::SinceTag & i_rData)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
Display_DT_Text(const DT_Text & i_rData)324 Docu_Display::Display_DT_Text( const DT_Text & i_rData )
325 {
326 Write_TextToken( i_rData.Text() );
327 }
328
329 void
Display_DT_MaybeLink(const DT_MaybeLink & i_rData)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
Display_DT_Whitespace(const DT_Whitespace & i_rData)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
Display_DT_Eol(const DT_Eol &)353 Docu_Display::Display_DT_Eol( const DT_Eol & )
354 {
355 CurOut() << new html::Sbr;
356 }
357
358 void
Display_DT_Xml(const ary::info::DT_Xml & i_rData)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 *
inq_Get_ReFinder() const365 Docu_Display::inq_Get_ReFinder() const
366 {
367 return &Env().Gate();
368 }
369
370 void
Start_DocuBlock()371 Docu_Display::Start_DocuBlock()
372 {
373 DYN DefList * dpDefList = new DefList;
374 CurOut() << dpDefList;
375 Easy().Enter( *dpDefList );
376 }
377
378 void
Finish_DocuBlock()379 Docu_Display::Finish_DocuBlock()
380 {
381 Easy().Leave();
382 }
383
384 void
Write_TagTitle(const char * i_sText,const char *)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
Write_TagContents(const DocuText & i_rDocuText)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
Write_Text(const ary::info::DocuText & i_rDocuText)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
Write_TextToken(const String & i_sText)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
Write_LinkableText(const ary::QualifiedName & i_sQuName)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
Write_QualifiedName(const ary::QualifiedName & i_sQuName)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