Doxygen
Loading...
Searching...
No Matches
DocSets Class Referencefinal

A class that generates docset files. More...

#include <src/docsets.h>

Inheritance diagram for DocSets:
Collaboration diagram for DocSets:

Classes

struct  Private

Public Member Functions

 DocSets ()
 ~DocSets ()
void initialize ()
void finalize ()
void incContentsDepth ()
void decContentsDepth ()
void addContentsItem (bool isDir, const DString &name, const DString &ref, const DString &file, const DString &anchor, bool separateIndex, bool addToNavIndex, const Definition *def, const DString &nameAsHtml)
void addIndexItem (const Definition *context, const MemberDef *md, const DString &sectionAnchor, const DString &title)
void addIndexFile (const DString &name)
void addImageFile (const DString &)
void addStyleSheetFile (const DString &)

Private Member Functions

void writeToken (TextStream &t, const Definition *d, const DString &type, const DString &lang, const DString &scope=DString(), const DString &anchor=DString(), const DString &decl=DString())

Private Attributes

std::unique_ptr< Private > p

Detailed Description

A class that generates docset files.

These files can be used to create context help for use within Apple's Xcode 3.0 development environment

Definition at line 34 of file docsets.h.

Constructor & Destructor Documentation

◆ DocSets()

DocSets::DocSets ( )

Definition at line 48 of file docsets.cpp.

48: p(std::make_unique<Private>()) {}
DocSets::p
std::unique_ptr< Private > p
Definition docsets.h:67

References p.

Referenced by ~DocSets().

◆ ~DocSets()

DocSets::~DocSets ( )
default

References DocSets().

Member Function Documentation

◆ addContentsItem()

void DocSets::addContentsItem ( bool isDir,
const DString & name,
const DString & ref,
const DString & file,
const DString & anchor,
bool separateIndex,
bool addToNavIndex,
const Definition * def,
const DString & nameAsHtml )
virtual

Implements IndexIntf.

Definition at line 229 of file docsets.cpp.

238{
239 //printf("DocSets::addContentsItem(%s) depth=%zu\n",name,p->indentStack.size());
240 if (ref==nullptr)
241 {
242 if (!p->indentStack.top())
243 {
244 p->nts << p->indent() << " </Node>\n";
245 }
246 p->indentStack.top()=false;
247 p->nts << p->indent() << " <Node>\n";
248 p->nts << p->indent() << " <Name>" << convertToXML(name) << "</Name>\n";
249 if (!file.empty() && file[0]=='^') // URL marker
250 {
251 p->nts << p->indent() << " <URL>" << convertToXML(&file[1])
252 << "</URL>\n";
253 }
254 else // relative file
255 {
256 p->nts << p->indent() << " <Path>";
257 if (!file.empty() && file[0]=='!') // user specified file
258 {
259 p->nts << convertToXML(&file[1]);
260 }
261 else if (!file.empty()) // doxygen generated file
262 {
263 DString fn = file;
264 addHtmlExtensionIfMissing(fn);
265 p->nts << fn;
266 }
267 p->nts << "</Path>\n";
268 if (!file.empty() && !anchor.empty())
269 {
270 p->nts << p->indent() << " <Anchor>" << anchor << "</Anchor>\n";
271 }
272 }
273 }
274}
DString::empty
bool empty() const
Returns true iff the string is empty (std::string compatible alias for isEmpty()).
Definition dstring.h:148
addHtmlExtensionIfMissing
void addHtmlExtensionIfMissing(DString &fName)
Definition util.cpp:3931
convertToXML
DString convertToXML(const DString &s, bool keepEntities, const bool citeEntry)
Definition util.cpp:3232

References addHtmlExtensionIfMissing(), convertToXML(), DString::empty(), and p.

◆ addImageFile()

void DocSets::addImageFile ( const DString & )
inlinevirtual

Implements IndexIntf.

Definition at line 58 of file docsets.h.

58{}

◆ addIndexFile()

void DocSets::addIndexFile ( const DString & name)
virtual

Implements IndexIntf.

Definition at line 514 of file docsets.cpp.

515{
516}

◆ addIndexItem()

void DocSets::addIndexItem ( const Definition * context,
const MemberDef * md,
const DString & sectionAnchor,
const DString & title )
virtual

Implements IndexIntf.

Definition at line 276 of file docsets.cpp.

278{
279 if (md==nullptr && context==nullptr) return;
280
281 const FileDef *fd = nullptr;
282 const ClassDef *cd = nullptr;
283 const NamespaceDef *nd = nullptr;
284
285 if (md)
286 {
287 fd = md->getFileDef();
288 cd = md->getClassDef();
289 nd = md->getNamespaceDef();
290 if (!md->isLinkable()) return; // internal symbol
291 }
292
293 DString scope;
294 DString type;
295 DString decl;
296
297 // determine language
298 DString lang;
299 SrcLangExt langExt = SrcLangExt::Cpp;
300 if (md)
301 {
302 langExt = md->getLanguage();
303 }
304 else if (context)
305 {
306 langExt = context->getLanguage();
307 }
308 switch (langExt)
309 {
310 case SrcLangExt::Cpp:
311 case SrcLangExt::ObjC:
312 {
313 if (md && (md->isObjCMethod() || md->isObjCProperty()))
314 lang="occ"; // Objective C/C++
315 else if (fd && fd->name().lower().endsWith(".c"))
316 lang="c"; // Plain C
317 else if (cd==nullptr && nd==nullptr)
318 lang="c"; // Plain C symbol outside any class or namespace
319 else
320 lang="cpp"; // C++
321 }
322 break;
323 case SrcLangExt::IDL: lang="idl"; break; // IDL
324 case SrcLangExt::CSharp: lang="csharp"; break; // C#
325 case SrcLangExt::PHP: lang="php"; break; // PHP4/5
326 case SrcLangExt::D: lang="d"; break; // D
327 case SrcLangExt::Java: lang="java"; break; // Java
328 case SrcLangExt::JS: lang="javascript"; break; // JavaScript
329 case SrcLangExt::Python: lang="python"; break; // Python
330 case SrcLangExt::Fortran: lang="fortran"; break; // Fortran
331 case SrcLangExt::VHDL: lang="vhdl"; break; // VHDL
332 case SrcLangExt::XML: lang="xml"; break; // DBUS XML
333 case SrcLangExt::SQL: lang="sql"; break; // Sql
334 case SrcLangExt::Markdown:lang="markdown"; break; // Markdown
335 case SrcLangExt::Slice: lang="slice"; break; // Slice
336 case SrcLangExt::Lex: lang="lex"; break; // Lex
337 case SrcLangExt::Unknown: lang="unknown"; break; // should not happen!
338 }
339
340 if (context && md)
341 {
342 switch (md->memberType())
343 {
344 case MemberType::Define:
345 type="macro"; break;
346 case MemberType::Function:
347 if (cd && (cd->compoundType()==ClassDef::Interface ||
348 cd->compoundType()==ClassDef::Class))
349 {
350 if (md->isStatic())
351 type="clm"; // class member
352 else
353 type="instm"; // instance member
354 }
355 else if (cd && cd->compoundType()==ClassDef::Protocol)
356 {
357 if (md->isStatic())
358 type="intfcm"; // interface class member
359 else
360 type="intfm"; // interface member
361 }
362 else
363 type="func";
364 break;
365 case MemberType::Variable:
366 type="data"; break;
367 case MemberType::Typedef:
368 type="tdef"; break;
369 case MemberType::Enumeration:
370 type="enum"; break;
371 case MemberType::EnumValue:
372 type="econst"; break;
373 //case MemberDef::Prototype:
374 // type="prototype"; break;
375 case MemberType::Signal:
376 type="signal"; break;
377 case MemberType::Slot:
378 type="slot"; break;
379 case MemberType::Friend:
380 type="ffunc"; break;
381 case MemberType::DCOP:
382 type="dcop"; break;
383 case MemberType::Property:
384 if (cd && cd->compoundType()==ClassDef::Protocol)
385 type="intfp"; // interface property
386 else
387 type="instp"; // instance property
388 break;
389 case MemberType::Event:
390 type="event"; break;
391 case MemberType::Interface:
392 type="ifc"; break;
393 case MemberType::Service:
394 type="svc"; break;
395 case MemberType::Sequence:
396 type="sequence"; break;
397 case MemberType::Dictionary:
398 type="dictionary"; break;
399 }
400 scope = md->getScopeString();
401 fd = md->getFileDef();
402 if (fd)
403 {
404 decl = fd->name();
405 }
406 writeToken(p->tts,md,type,lang,scope,md->anchor(),decl);
407 }
408 else if (context && context->isLinkable())
409 {
410 if (fd==nullptr && context->definitionType()==Definition::TypeFile)
411 {
412 fd = toFileDef(context);
413 }
414 if (cd==nullptr && context->definitionType()==Definition::TypeClass)
415 {
416 cd = toClassDef(context);
417 }
418 if (nd==nullptr && context->definitionType()==Definition::TypeNamespace)
419 {
420 nd = toNamespaceDef(context);
421 }
422 if (fd)
423 {
424 type="file";
425 }
426 else if (cd)
427 {
428 scope = cd->qualifiedName();
429 if (cd->isTemplate())
430 {
431 type="tmplt";
432 }
433 else if (cd->compoundType()==ClassDef::Protocol)
434 {
435 type="intf";
436 if (scope.endsWith("-p")) scope=scope.left(scope.length()-2);
437 }
438 else if (cd->compoundType()==ClassDef::Interface)
439 {
440 type="cl";
441 }
442 else if (cd->compoundType()==ClassDef::Category)
443 {
444 type="cat";
445 }
446 else
447 {
448 type = "cl";
449 }
450 const IncludeInfo *ii = cd->includeInfo();
451 if (ii)
452 {
453 decl=ii->includeName;
454 }
455 }
456 else if (nd)
457 {
458 scope = nd->name();
459 type = "ns";
460 }
461 if (p->scopes.find(context->getOutputFileBase().str())==p->scopes.end())
462 {
463 writeToken(p->tts,context,type,lang,scope,DString(),decl);
464 p->scopes.insert(context->getOutputFileBase().str());
465 }
466 }
467}
ClassDef::isTemplate
virtual bool isTemplate() const =0
Returns true if this class is a template.
ClassDef::Interface
@ Interface
Definition classdef.h:108
ClassDef::compoundType
virtual CompoundType compoundType() const =0
Returns the type of compound this is, i.e. class/struct/union/...
ClassDef::includeInfo
virtual const IncludeInfo * includeInfo() const =0
DString::lower
DString lower() const
Definition dstring.h:326
DString::left
DString left(size_t len) const
Definition dstring.h:306
DString::str
const std::string & str() const
Definition dstring.h:645
DString::endsWith
bool endsWith(const char *s) const
Definition dstring.h:617
DString::length
size_t length() const
Returns the length of the string, not counting the 0-terminator.
Definition dstring.h:151
Definition::getLanguage
virtual SrcLangExt getLanguage() const =0
Returns the programming language this definition was written in.
Definition::isLinkable
virtual bool isLinkable() const =0
Definition::definitionType
virtual DefType definitionType() const =0
Definition::name
virtual const DString & name() const =0
Definition::qualifiedName
virtual DString qualifiedName() const =0
Definition::anchor
virtual DString anchor() const =0
Definition::getOutputFileBase
virtual DString getOutputFileBase() const =0
DocSets::writeToken
void writeToken(TextStream &t, const Definition *d, const DString &type, const DString &lang, const DString &scope=DString(), const DString &anchor=DString(), const DString &decl=DString())
Definition docsets.cpp:469
IncludeInfo::includeName
DString includeName
Definition filedef.h:78
MemberDef::isObjCMethod
virtual bool isObjCMethod() const =0
MemberDef::getClassDef
virtual const ClassDef * getClassDef() const =0
MemberDef::getFileDef
virtual const FileDef * getFileDef() const =0
MemberDef::isStatic
virtual bool isStatic() const =0
MemberDef::getNamespaceDef
virtual const NamespaceDef * getNamespaceDef() const =0
MemberDef::getScopeString
virtual DString getScopeString() const =0
MemberDef::isObjCProperty
virtual bool isObjCProperty() const =0
MemberDef::memberType
virtual MemberType memberType() const =0
toClassDef
ClassDef * toClassDef(Definition *d)
Definition classdef.cpp:5455
toFileDef
FileDef * toFileDef(Definition *d)
Definition filedef.cpp:2028
toNamespaceDef
NamespaceDef * toNamespaceDef(Definition *d)
Definition namespacedef.cpp:1755
SrcLangExt
SrcLangExt
Definition types.h:207

References Definition::anchor(), ClassDef::Category, ClassDef::Class, ClassDef::compoundType(), Definition::definitionType(), DString::endsWith(), MemberDef::getClassDef(), MemberDef::getFileDef(), Definition::getLanguage(), MemberDef::getNamespaceDef(), Definition::getOutputFileBase(), MemberDef::getScopeString(), ClassDef::includeInfo(), IncludeInfo::includeName, ClassDef::Interface, Definition::isLinkable(), MemberDef::isObjCMethod(), MemberDef::isObjCProperty(), MemberDef::isStatic(), ClassDef::isTemplate(), DString::left(), DString::length(), DString::lower(), MemberDef::memberType(), Definition::name(), p, ClassDef::Protocol, Definition::qualifiedName(), DString::str(), toClassDef(), toFileDef(), toNamespaceDef(), Definition::TypeClass, Definition::TypeFile, Definition::TypeNamespace, and writeToken().

◆ addStyleSheetFile()

void DocSets::addStyleSheetFile ( const DString & )
inlinevirtual

Implements IndexIntf.

Definition at line 59 of file docsets.h.

59{}

◆ decContentsDepth()

void DocSets::decContentsDepth ( )
virtual

Implements IndexIntf.

Definition at line 218 of file docsets.cpp.

219{
220 if (!p->indentStack.top())
221 {
222 p->nts << p->indent() << " </Node>\n";
223 }
224 p->nts << p->indent() << "</Subnodes>\n";
225 p->indentStack.pop();
226 //printf("DocSets::decContentsDepth() depth=%zu\n",p->indentStack.size());
227}

References p.

◆ finalize()

void DocSets::finalize ( )
virtual

Implements IndexIntf.

Definition at line 185 of file docsets.cpp.

186{
187 if (!p->indentStack.top())
188 {
189 p->nts << p->indent() << " </Node>\n";
190 }
191 p->indentStack.pop();
192 p->nts << " </Subnodes>\n";
193 p->nts << " </Node>\n";
194 p->nts << " </TOC>\n";
195 p->nts << "</DocSetNodes>\n";
196 p->nts.flush();
197 p->ntf.close();
198
199 p->tts << "</Tokens>\n";
200 p->tts.flush();
201 p->ttf.close();
202}

References p.

◆ incContentsDepth()

void DocSets::incContentsDepth ( )
virtual

Implements IndexIntf.

Definition at line 211 of file docsets.cpp.

212{
213 //printf("DocSets::incContentsDepth() depth=%zu\n",p->indentStack.size());
214 p->nts << p->indent() << "<Subnodes>\n";
215 p->indentStack.push(true);
216}

References p.

◆ initialize()

void DocSets::initialize ( )
virtual

Implements IndexIntf.

Definition at line 51 of file docsets.cpp.

52{
53 // -- get config options
54 DString projectName = Config_getString(PROJECT_NAME);
55 if (projectName.empty()) projectName="root";
56 DString bundleId = Config_getString(DOCSET_BUNDLE_ID);
57 if (bundleId.empty()) bundleId="org.doxygen.Project";
58 DString feedName = Config_getString(DOCSET_FEEDNAME);
59 if (feedName.empty()) feedName="FeedName";
60 DString feedURL = Config_getString(DOCSET_FEEDURL);
61 if (feedURL.empty()) feedURL="FeedUrl";
62 DString publisherId = Config_getString(DOCSET_PUBLISHER_ID);
63 if (publisherId.empty()) publisherId="PublisherId";
64 DString publisherName = Config_getString(DOCSET_PUBLISHER_NAME);
65 if (publisherName.empty()) publisherName="PublisherName";
66 DString projectNumber = Config_getString(PROJECT_NUMBER);
67 if (projectNumber.empty()) projectNumber="ProjectNumber";
68
69 // -- write Makefile
70 {
71 DString mfName = Config_getString(HTML_OUTPUT) + "/Makefile";
72 std::ofstream ts = Portable::openOutputStream(mfName);
73 if (!ts.is_open())
74 {
75 term("Could not open file {} for writing\n",mfName);
76 }
77
78 ts << "DOCSET_NAME=" << bundleId << ".docset\n"
79 "DOCSET_CONTENTS=$(DOCSET_NAME)/Contents\n"
80 "DOCSET_RESOURCES=$(DOCSET_CONTENTS)/Resources\n"
81 "DOCSET_DOCUMENTS=$(DOCSET_RESOURCES)/Documents\n"
82 "DESTDIR=~/Library/Developer/Shared/Documentation/DocSets\n"
83 "XCODE_INSTALL=\"$(shell xcode-select -print-path)\"\n"
84 "\n"
85 "all: docset\n"
86 "\n"
87 "docset:\n"
88 "\tmkdir -p $(DOCSET_DOCUMENTS)\n"
89 "\tcp Nodes.xml $(DOCSET_RESOURCES)\n"
90 "\tcp Tokens.xml $(DOCSET_RESOURCES)\n"
91 "\tcp Info.plist $(DOCSET_CONTENTS)\n"
92 "\ttar --exclude $(DOCSET_NAME) \\\n"
93 "\t --exclude Nodes.xml \\\n"
94 "\t --exclude Tokens.xml \\\n"
95 "\t --exclude Info.plist \\\n"
96 "\t --exclude Makefile -c -f - . \\\n"
97 "\t | (cd $(DOCSET_DOCUMENTS); tar xvf -)\n"
98 "\t$(XCODE_INSTALL)/usr/bin/docsetutil index $(DOCSET_NAME)\n"
99 "\trm -f $(DOCSET_DOCUMENTS)/Nodes.xml\n"
100 "\trm -f $(DOCSET_DOCUMENTS)/Info.plist\n"
101 "\trm -f $(DOCSET_DOCUMENTS)/Makefile\n"
102 "\trm -f $(DOCSET_RESOURCES)/Nodes.xml\n"
103 "\trm -f $(DOCSET_RESOURCES)/Tokens.xml\n"
104 "\n"
105 "clean:\n"
106 "\trm -rf $(DOCSET_NAME)\n"
107 "\n"
108 "install: docset\n"
109 "\tmkdir -p $(DESTDIR)\n"
110 "\tcp -R $(DOCSET_NAME) $(DESTDIR)\n"
111 "\n"
112 "uninstall:\n"
113 "\trm -rf $(DESTDIR)/$(DOCSET_NAME)\n"
114 "\n"
115 "always:\n";
116 }
117
118 // -- write Info.plist
119 {
120 DString plName = Config_getString(HTML_OUTPUT) + "/Info.plist";
121 std::ofstream ts = Portable::openOutputStream(plName);
122 if (!ts.is_open())
123 {
124 term("Could not open file {} for writing\n",plName);
125 }
126
127 ts << "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
128 "<!DOCTYPE plist PUBLIC \"-//Apple Computer//DTD PLIST 1.0//EN\"\n"
129 "\"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n"
130 "<plist version=\"1.0\">\n"
131 "<dict>\n"
132 " <key>CFBundleName</key>\n"
133 " <string>" << projectName << "</string>\n"
134 " <key>CFBundleIdentifier</key>\n"
135 " <string>" << bundleId << "</string>\n"
136 " <key>CFBundleVersion</key>\n"
137 " <string>" << projectNumber << "</string>\n"
138 " <key>DocSetFeedName</key>\n"
139 " <string>" << feedName << "</string>\n"
140 " <key>DocSetFeedUrl</key>\n"
141 " <string>" << feedURL << "</string>\n"
142 " <key>DocSetPublisherIdentifier</key>\n"
143 " <string>" << publisherId << "</string>\n"
144 " <key>DocSetPublisherName</key>\n"
145 " <string>" << publisherName << "</string>\n"
146 // markers for Dash
147 " <key>DashDocSetFamily</key>\n"
148 " <string>doxy</string>\n"
149 " <key>DocSetPlatformFamily</key>\n"
150 " <string>doxygen</string>\n"
151 "</dict>\n"
152 "</plist>\n";
153 }
154
155 // -- start Nodes.xml
156 DString notes = Config_getString(HTML_OUTPUT) + "/Nodes.xml";
157 p->ntf = Portable::openOutputStream(notes);
158 if (!p->ntf.is_open())
159 {
160 term("Could not open file {} for writing\n",notes);
161 }
162 p->nts.setStream(&p->ntf);
163 //DString indexName=Config_getBool(GENERATE_TREEVIEW)?"main":"index";
164 DString indexName="index";
165 p->nts << "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
166 p->nts << "<DocSetNodes version=\"1.0\">\n";
167 p->nts << " <TOC>\n";
168 p->nts << " <Node>\n";
169 p->nts << " <Name>Root</Name>\n";
170 p->nts << " <Path>" << indexName << Doxygen::htmlFileExtension << "</Path>\n";
171 p->nts << " <Subnodes>\n";
172 p->indentStack.push(true);
173
174 DString tokens = Config_getString(HTML_OUTPUT) + "/Tokens.xml";
175 p->ttf = Portable::openOutputStream(tokens);
176 if (!p->ttf.is_open())
177 {
178 term("Could not open file {} for writing\n",tokens);
179 }
180 p->tts.setStream(&p->ttf);
181 p->tts << "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
182 p->tts << "<Tokens version=\"1.0\">\n";
183}
Doxygen::htmlFileExtension
static DString htmlFileExtension
Definition doxygen.h:115
Config_getString
#define Config_getString(name)
Definition config.h:32
term
#define term(fmt,...)
Definition message.h:137
Portable::openOutputStream
std::ofstream openOutputStream(const DString &name, bool append=false)
Definition portable.cpp:681

References Config_getString, DString::empty(), Doxygen::htmlFileExtension, Portable::openOutputStream(), p, and term.

◆ writeToken()

void DocSets::writeToken ( TextStream & t,
const Definition * d,
const DString & type,
const DString & lang,
const DString & scope = DString(),
const DString & anchor = DString(),
const DString & decl = DString() )
private

Definition at line 469 of file docsets.cpp.

476{
477 t << " <Token>\n";
478 t << " <TokenIdentifier>\n";
479 DString name = d->name();
480 if (name.endsWith("-p")) name=name.left(name.length()-2);
481 t << " <Name>" << convertToXML(name) << "</Name>\n";
482 if (!lang.empty())
483 {
484 t << " <APILanguage>" << lang << "</APILanguage>\n";
485 }
486 if (!type.empty())
487 {
488 t << " <Type>" << type << "</Type>\n";
489 }
490 if (!scope.empty())
491 {
492 t << " <Scope>" << convertToXML(scope) << "</Scope>\n";
493 }
494 t << " </TokenIdentifier>\n";
495 DString fn = d->getOutputFileBase();
496 addHtmlExtensionIfMissing(fn);
497 t << " <Path>" << fn << "</Path>\n";
498 if (!anchor.empty())
499 {
500 t << " <Anchor>" << anchor << "</Anchor>\n";
501 }
502 DString tooltip = d->briefDescriptionAsTooltip();
503 if (!tooltip.empty())
504 {
505 t << " <Abstract>" << convertToXML(tooltip) << "</Abstract>\n";
506 }
507 if (!decl.empty())
508 {
509 t << " <DeclaredIn>" << convertToXML(decl) << "</DeclaredIn>\n";
510 }
511 t << " </Token>\n";
512}
Definition::briefDescriptionAsTooltip
virtual DString briefDescriptionAsTooltip() const =0

References addHtmlExtensionIfMissing(), Definition::briefDescriptionAsTooltip(), convertToXML(), DString::empty(), DString::endsWith(), Definition::getOutputFileBase(), DString::left(), DString::length(), and Definition::name().

Referenced by addIndexItem().

Member Data Documentation

◆ p

std::unique_ptr<Private> DocSets::p
private

Definition at line 67 of file docsets.h.

Referenced by addContentsItem(), addIndexItem(), decContentsDepth(), DocSets(), finalize(), incContentsDepth(), and initialize().

The documentation for this class was generated from the following files: