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 QCString &name, const QCString &ref, const QCString &file, const QCString &anchor, bool separateIndex, bool addToNavIndex, const Definition *def, const QCString &nameAsHtml)
void addIndexItem (const Definition *context, const MemberDef *md, const QCString &sectionAnchor, const QCString &title)
void addIndexFile (const QCString &name)
void addImageFile (const QCString &)
void addStyleSheetFile (const QCString &)

Private Member Functions

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

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 35 of file docsets.h.

Constructor & Destructor Documentation

◆ DocSets()

DocSets::DocSets ( )

Definition at line 44 of file docsets.cpp.

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

References p.

Referenced by ~DocSets().

◆ ~DocSets()

DocSets::~DocSets ( )
default

References DocSets().

Member Function Documentation

◆ addContentsItem()

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

Implements IndexIntf.

Definition at line 225 of file docsets.cpp.

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

References addHtmlExtensionIfMissing(), convertToXML(), QCString::isEmpty(), and p.

◆ addImageFile()

void DocSets::addImageFile ( const QCString & )
inlinevirtual

Implements IndexIntf.

Definition at line 59 of file docsets.h.

59{}

◆ addIndexFile()

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

Implements IndexIntf.

Definition at line 510 of file docsets.cpp.

511{
512}

◆ addIndexItem()

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

Implements IndexIntf.

Definition at line 272 of file docsets.cpp.

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

References Definition::anchor(), ClassDef::Category, ClassDef::Class, ClassDef::compoundType(), Definition::definitionType(), QCString::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(), QCString::left(), QCString::length(), QCString::lower(), MemberDef::memberType(), Definition::name(), p, ClassDef::Protocol, Definition::qualifiedName(), QCString::str(), toClassDef(), toFileDef(), toNamespaceDef(), Definition::TypeClass, Definition::TypeFile, Definition::TypeNamespace, and writeToken().

◆ addStyleSheetFile()

void DocSets::addStyleSheetFile ( const QCString & )
inlinevirtual

Implements IndexIntf.

Definition at line 60 of file docsets.h.

60{}

◆ decContentsDepth()

void DocSets::decContentsDepth ( )
virtual

Implements IndexIntf.

Definition at line 214 of file docsets.cpp.

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

References p.

◆ finalize()

void DocSets::finalize ( )
virtual

Implements IndexIntf.

Definition at line 181 of file docsets.cpp.

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

References p.

◆ incContentsDepth()

void DocSets::incContentsDepth ( )
virtual

Implements IndexIntf.

Definition at line 207 of file docsets.cpp.

208{
209 //printf("DocSets::incContentsDepth() depth=%zu\n",p->indentStack.size());
210 p->nts << p->indent() << "<Subnodes>\n";
211 p->indentStack.push(true);
212}

References p.

◆ initialize()

void DocSets::initialize ( )
virtual

Implements IndexIntf.

Definition at line 47 of file docsets.cpp.

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

References Config_getString, Doxygen::htmlFileExtension, QCString::isEmpty(), Portable::openOutputStream(), p, and term.

◆ writeToken()

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

Definition at line 465 of file docsets.cpp.

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

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

Referenced by addIndexItem().

Member Data Documentation

◆ p

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

Definition at line 68 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: