| Commit message (Collapse) | Author | Age | Files | Lines |
|---|
| |
|
|
|
|
|
|
|
|
|
|
| |
There is no need to pass a pointer to Config throughout
the API; the only instance of it is created in main()
so we can turn it into a singleton.
Having access to Config without API changes makes
implementation of configurable features easier.
Change-Id: Ida47e067865082dfe036a7a97f7f1ffc736db346
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This patch is the result of formatting all of QDoc's source with
clang-format. The clang-format style is from the qt5 super repo's
_clang-format definition.
The purpose is unify the style across the code, to avoid spending too
much time on style related issues in reviews and cleanup patches. Future
changes to QDoc can benefit from using git-clang-format in combination
with the git commit hook provided in qtrepotools.git as mentioned in
this email to the dev list:
https://lists.qt-project.org/pipermail/development/2019-October/037682.html
Change-Id: I8af6a051c8334b5f35862a4dcd3becce8ac500c2
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
| |
HTML, WebXML, and the future DocBook output
Fixes: QTBUG-80100
Change-Id: Idf373e3b1d76ab808597dcabd8649ecb5e2df0f7
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
| |
The inline and auto links were handled differently compared to
the members list for a group page. This change reuses the same
code for generating any kind of link.
This change amends 8f5ebc02f6653e
Change-Id: Ic9d2bf00a95c718d6074ec2b0b4705324cccf053
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |\
| |
| |
| | |
Change-Id: I5c06b3e0177fcccd988620ab269f75632689a54c
|
| | |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
The WebXMLGenerator did not handle atoms of type AnnotatedList. Adding
this enables listing of grouped pages with the \annotatedlist command.
Similarly, empty output page was generated for the \group page itself.
This was because QDocIndexFiles::generateIndexSections() only handled
groups when processing the root node, which we must skip in this
generator.
Add explicit handling for group nodes, enabling us to receive
callbacks from QDocIndexFiles to add content for these pages.
Task-number: PYSIDE-1088
Change-Id: Id72d589a51fc7aae21ad5cdbb3c1dfa78d4c23ae
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| | |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
Since QDoc no longer stores example files as nodes in its tree, the
WebXMLGenerator failed to generate output for those files.
Fix this by generating those pages explicitly as needed, overriding
functions from the Generator base class.
Prevent QDocIndexFiles from writing nested <page> elements when
WebXMLGenerator is in use, as that does not work as expected with
shiboken2.
Fixes: PYSIDE-1088
Change-Id: I01c2af2391726f448271fdb810ffc3da923caca5
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| | |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
This change removes reduntant destructors. It also adds the
'override' keyword to overridden destructors to remove warnings
from clang-tidy in Creator.
The patch also replaces two instances of 0 as nullptr constant.
Change-Id: I576c248b7d4637249d167d7bfb8885af4f7811ff
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
|
| |/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Housekeeping. Includes are organized after recommended best practice and
organized in the following order:
- include self (i.e. include own header)
- include local files
- include Qt, e.g. <QtCore/qstring.h>
- include Qt private
- include externals, e.g. stdio.h
in alphabetic order within each block, aside from accommodating #if-ery,
in which includes follow the block they belong to.
Also, updated copyright notice to year of latest edit in each file.
Change-Id: I1e6b215f172fd5373d57016f7678b88b9e73231e
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
An update to qdoc that refactored the index file output was not reflected
in the webxmlgenerator.
This commit implements a callback interface between QDocIndexFiles and
WebXMLGenerator to enable the latter to append documentation to generated
elements. This also eliminates virtually all duplicated logic between the
two classes.
Fixes: QTBUG-74424
Change-Id: Ia302bbfd290c8d74591cb4804458d5b73c301378
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This update was motivated by the need to correct two known issues
in qdoc. First, linking to overloaded functions failed in some cases
because the overloads were not numbered consistently, causing links
to go to the wrong overload or to nowhere at all. Second, the
mechanism for handling the \relates command didn't support using it to
relate a function to more than one class.
For example, there are many global qHash() functions spread
around QtBase. Each is meant to compute a hash index for an
object of some class type, so the object can be inserted into a
QHash map for that class type. It is then desired to relate
qHash(type Xxx, int seed) to both QHash<type> and class Xxx, so
that the documentation for that qHash() function appears as a
related non-member function of both QHash<type> and class Xxx.
The example above also illustrates the overload numbering problem,
because all these qHash() functions are overloads of the name
qHash. To make matters worse, they are not all in the same module.
Most of them are in QtCore, but a few are in QtNetwork, and this
distribution problem will become worse over time as more qHash()
functions are added. Prior to this update, qdoc was unable to
relate a function to something in a different module, or it didn't
always work.
While designing a fix for these issues, it became clear that the
processing of the FunctionNode and the function parameters would
have to be rewritten. That's what this update does. These are
the main points:
1. A new subclass of Node is added to act as a proxy for a class
in another module. This ProxyNode acts as a place holder for the
functions (and possibly other elements) that are related to a
class in another module. This is used for the qHash() functions
in QtNetwork that are related to QHash in QtCore. qdoc generates
an html file named qtnetwork/qhash-proxy.html that contains the
documentation for these functions. But these functions are listed
as related non-members on the QHash class reference page in the
qtcore output directory. They are listed there in the summary,
but they link to the qhash-proxy.html page in qtnetwork.
2. A new, Parameters class is added to qdoc (parameters.h and
parameters.cpp), and the class Parameter is moved there from
node.h. class Parameters replaces the old QVector<Parameter>
wherever it was used. This encapsulates all the parameter
processing and matching in the Parameters class and simplifies
the code at all the places where QVector<Parameter> had been
used.
3. The assignment of overload numbers is now done in the
normalizeOverloads() function, which is called after all the
headers and sources have been processed but before the
generate phase begins. This assignment is a simple renumbering
now because all the overloads of a function are linked to
each other via a nextOverload_ link in the FunctionNode. The
first function named qHash() is inserted into the Aggregate
node's function map, but subsequent qHash() FunctionNodes
are not entered into the function map but are linked to the
first qHash() via its nextOverload_ link.
4. The \relates command can now be used multiple times in a
single qdoc comment. There remains some work to be done here
because this currently only works for global entities, but
there are several cases where \relates has been used in the
qdoc comment of a member of a class. This will be fixed soon,
I believe.
When qdoc sees the first \relates Xxx command, for example
for qHash(Yyy, seed), that qHash() is a child of the global
namespace. qdoc allows it to remain as a child of the global
namespace but it tells class Xxx to "adopt" that child (see
Node::adoptChild()). This function makes this instance of
qHash() be a child of class Xxx (in this case QHash<type>),
so that the parent of this qHash() becomes Xxx. After this
"adoption," qHash() is a child of both the global namespace
and class Xxx, but qHash() only knows it is a child of Xxx,
i.e. its parent pointer is Xxx. If this is the first qHash()
to become a child of Xxx, it is inserted into the function
map of Xxx, but its nextOverload_ link is not changed. This
is because all the global qHash() functions have already been
linked into the nextOverload_ linked list, and this list must
not be changed. Hence, when qdoc searches for qHash(something)
to make a link to it, it will find it as a child of the global
namespace, but it will correctly link to it using its actual
parent pointer.
When qdoc sees the second \relates Yyy for this qHash()
function, qdoc sees that this FunctionNode has already been
made a related non-member of Xxx, so it can't let Yyy "adopt"
it. Instead, it tells Yyy to clone this qHash(), which creates
a shallow copy of it but resets its nextOverload_ pointer to
nullptr. I believe this clone of qHash() won't be found in a
search for a function named qHash(), because the global one
(the adopted one) will be found first. Or, if it is found, a
link to the clone will be generated, but that's ok because
the documentation is identical.
Note that the existence of qHash in two child lists is taken
into account at destruction time. The only place where a Node
is destroyed is in the destructor of Tree, which destroys the
Node tree from the root down to the leaves. Each aggregate
node is responsible for deleting each of its child nodes, but
it only deletes a child node if it is the parent of that child
node.
All of the above revealed that some of the findFunctionNode()
functions were either no longer needed or weren't being called
in the first place, so they were deleted.
This change is now ready for testing.
Change-Id: I6da3e2e9e71d39a29d90e073ed614309a49e3d4c
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
This is a significant refactoring of QDoc's Node class hierarchy,
which is meant to make maintenance of QDoc easier, and which will
enable further development of QDoc as a library and plugin.
Class DocumentNode is renamed to class PageNode, and it inherits
the Node base class instead of inheriting class Aggregate. Class
Aggregate inherits class PageNode instead of the Node base class.
IOW, class DocumentNode and class Aggregate have swapped places
in the class hierarchy, and DocumentNode has changed its name to
PageNode.
This makes the Node hierarchy more logical because:
1. Every entity that causes a documentation page to be written
is a PageNode.
2. Only those PageNodes that can have children are Aggregates.
Thus the HeaderFile subtype of the former DocumentNode has been
promoted to class HeaderNode, which is a subclass of Aggregate.
This makes sense because the old HeaderFile DocumentNode caused
a documentation page to be generated, and that documentation page
was very much like a class reference page. The \headerfile command
is not used a lot in the Qt documentation but there are some useful
cases, so it is worth making a subclass of Aggregate to handle them.
The HeaderNode is now processed very much like the ClassNode and the
NamespaceNode.
Developers should be advised that isDocumentNode() is now isPageNode(),
but isPageNode() can no longer be used to decide if an Aggregate* is
a PageNode* (DocumentNode*), because Aggregate is now a subclass of
PageNode. So a new convenience function is added: isTextPageNode(),
which returns true if your Node* is a PageNode but not an Aggregate.
IOW, isTextPageNode() returns true if the Node* is some kind of text
page that doesn't represent a C++ or QML declaration.
Class ExampleNode is a subclass of PageNode, not Aggregate. IOW, an
ExampleNode no longer has children. Instead, the example files and
example images that belong to the example are stored as string lists.
It seems to work, but there might be problems in help files I haven't
found yet.
Class CollectionNode is now a subclass of Node instead of LeafNode.
Class LeafNode is removed. All former subclasses of LeafNode are now
subclasses of Node.
This change also removes a lot of DITA bitrot.
Work remaining to be done:
1. Remove the remaining DITA bitrot.
2. Consider letting QmlProperty and JsProperty be instances of Property
and use the Genus value to distiguish them.
3. Also consider replacing QmlPropertyGroup and JsPropertyGroup with a
single PropertyGroup and use the Genus value to distinguish them.
This update also rearranges the parameters passed to the clang parser,
and it removes some diff conflict lines that got saved by mistake.
Change-Id: I918f83030c48d96db4a5588ab53458f221a5374e
Reviewed-by: Martin Smith <martin.smith@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
qdoc didn't handle this. This update fixes most of what was wrong,
but tuning the details of the namespace reference pages might follow.
We have namespace Qt as an example. Most of the elements in the Qt
namespace are in QtCore, but a few functions are declared in QtGui.
Before this update, qdoc used the hack of using #ifdef to remove the
declarations from qtextdocument.h in QtGui and .cpp and then added
them back into qtnamespace.h and .cpp in QtCore.
Now that hack is no longer necessary. The functions in the Qt namespace
that are declared in QtGui are documented there, but the documentation
is linked to from the namespace reference page, which remains in QtCore.
That is, only one \namespace command is used to document the Qt namespace,
and it appears in qnamespace.qdoc where it always did, but the documentation
for the Qt namespace functions declared in QtGui is now appears in
qtextdocument.cpp where it belongs.
This also allows qdoc to report when a namespace contains elements that are
public and documented, but the namespace itself is not documented, which was
not possible before this change. qdoc also reports if a namespace is documented
in more than one module. That is, for example, when \namespace Qt is used in
both QtCore and QtGui.
Note that this change will increase the number of qdoc warnings in
QtBase, but the new warnings are expacted.
Change-Id: If978a59209b7b2ae90713d3ae809ae03361df72f
Task-number: QTBUG-67267
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
| |
Ironically, The Node suclass CollectionNode should not be a
subclass of Aggregate because CollectionNode never has children.
It only has members, which are children of other Aggregate nodes.
This update makes CollectionNode a subclass of LeafNode instead
of Aggregate. This refactoring is necessary to implement the task
QTBUG-45725.
Change-Id: I60b2dcdaa3da1d138a0e6b4eb3d4f78cba0053d4
Task-number: QTBUG-45725
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
| |
Change-Id: Ie9cd9568fc7439dddb5f46b0f9fd58ecb72ff861
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
With the introduction of the WebXML output format, QDoc can no longer
assume that the configuration is specific to HTML. In particular,
Config variables:
- Output directory and subdirectory can now be set for each format.
- 'quotinginformation' can now be prefixed with '<format>.' qualifier.
Because the same parsed tree of atoms is used for all generators,
we need to include both the quoting information and the related
code snippets in the list of atoms; generators then decide what to
include in the output.
Index files:
- Look for index files under the output subdirectory for each specified
format.
This allows per-format configuration and passing multiple formats in
'outputformats' configuration variable.
Clean up and refactor the code related to processing doc config
variables.
Task-number: PYSIDE-363
Change-Id: I66e9c71311689a777fcb445d3b1a8ef070dff93d
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
|
|
|
Reintroduce the WebXML generator that was last seen in Qt 4.7 - this
generator produces XML output similar to .index files, with embedded
documentation content. To be used for generating documentation for the
PySide project.
Uses code from QDocIndexFiles to generate the elements. The generator
itself is a specialization of the HTML generator as a lot of the code
common to all generators is implemented in the HTML generator and not
the base class. This could be cleaned up later on.
To use the generator, set the 'outputformats' .qdocconf variable:
outputformats = WebXML
In addition for PySide/Shiboken, \snippet commands must be
configured to generate <snippet> elements instead of hardcoded
<code> snippets:
quotinginformation = true
Task-number: PYSIDE-363
Change-Id: I6b0770c5cd0db3e374f63f9c437fa9e8a77d3f8d
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Martin Smith <martin.smith@qt.io>
|
