summaryrefslogtreecommitdiff
path: root/src/qdoc/doc.cpp
Commit message (Collapse)AuthorAgeFilesLines
...
* QDoc: Clean up whitespacePaul Wicking2019-08-081-59/+59
| | | | | | | | | | | Ensure that QDoc conforms to Qt style, whitespace edition. For the most part, the change involves moving the pointer operators. Also remove whitespace following an opening parenthesis, or immediately preceding a closing one. In some cases, adjust the following line accordingly in methods that span multiple lines. Change-Id: I56ae125a2acf09c669c0a73dc814d05f13575f39 Reviewed-by: Martin Smith <martin.smith@qt.io>
* QDoc: Ensure all includes are uniform and according to stylePaul Wicking2019-08-031-12/+15
| | | | | | | | | | | | | | | | | | | 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>
* qdoc: Don't report override error when reimp is usedMartin Smith2019-04-051-0/+9
| | | | | | | | | | qdoc was reporting an error when the reimplementation of a virtual function that was documented in the base class was given a qdoc comment in the derived class that only contained the \reimp command. When the reimp command is used, the error should not be reported. This change implements that. Change-Id: I6905e35b4e9c3df12617446c04eb9ea6d1804832 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Search for QML type before creating itMartin Smith2019-04-021-2/+2
| | | | | | | | | | | | | | | | | | | | Because we have QML types that represent C++ classes, it is possible for qdoc to process a \qmlproperty command before it has processed the \qmltype for the QML type where the QML property belongs. This is because the \qmlproperty command can appear in a different .cpp file from the one containing the \qmltype command. If the .cpp file is parsed first, the QML type node won't exist when the \qmlproperty is processed, resulting in a qdoc error. This update forces qdoc to always check for the exist of the QML type before creating it and before creating any QML properties for it, and if the QML type does not exist, create it. If it does exist, use it. Change-Id: I78705aa95ee5bf3abc2e17fb2b6cd52191d54b68 Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* qdoc: Eliminate need for the property group commandsMartin Smith2019-04-021-3/+8
| | | | | | | | | | | | | | | We have been using the \qmlpropertygroup command to document complex properties. we also have the \jspropertygroup but it hasn't been used. However, we also have the shared comment concept, which we have used for documenting groups of functions. This update changes qdoc to use the shared comment concept for QML and JS property groups. The property groups commands are therefore no longer needed. But there are several uses of the \qmlpropertygroup command, and qdoc still recognizes these, although it uses the shared comment concept to handle them. The property group commands will be removed from the qdoc manual in a later update. Change-Id: Ie98638546756fd1a70067a7cd483c3b962c02954 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QDoc: filter out internal nodes when processing argsMartin Smith2019-01-231-0/+9
| | | | | | | | | | CppCodeParser::processTopicArgs() neglected to check whether nodes are internal (or internals are to be included) before including them. Add Doc::isInternal() and CodeParser::showInternal() to let it check this and add the check. Tidied up surrounding code in the process. Change-Id: I9e1ca379a8e58c1519c345bbf98f441915998061 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Remove unused method Doc::renameParameters()Martin Smith2019-01-221-24/+0
| | | | | | Change-Id: I5e0b940ff6ae3cd9ea7aec526ecacd7956511dd4 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Reorganize Qdoc's Node class hierarchyMartin Smith2018-10-231-7/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* Merge remote-tracking branch 'origin/5.12' into devLiang Qi2018-09-121-27/+70
|\ | | | | | | | | | | | | Conflicts: src/qdoc/doc.cpp Change-Id: I8f644a40bcb3d8a435e06298d04376c86a1411aa
| * qdoc: Allow parameters for \code, \qml, \js, and \badcode commandsTopi Reinio2018-09-091-6/+28
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Allow optional parameters for commands that enclose code snippets. This is intended for replacing simple strings within the snippet, typically using a macro that extends to certain parameter(s). Within the snippet, the parameter locations are marked similarly to .qdocconf macro parameters: \code foo bar \1+\2=\1\2 \encode Renders "foo+bar=foobar" A code snippet parameter cannot contain spaces, as space is used as a delimiter. If no parameters are passed, the snippet is rendered as-is. Task-number: QTBUG-67818 Change-Id: I500e6b1a9095c9c55f47c8d75951792f31745545 Reviewed-by: Martin Smith <martin.smith@qt.io>
| * qdoc: Add regular expression matching to macrosTopi Reinio2018-09-091-20/+41
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This commit adds support for a special format (.match) option to QDoc macros. The use case is to do additional regular expression pattern matching for expanded macros; For example, macro.qtminorversion = "$QT_VER" macro.qtminorversion.match = "\\d+\\.(\\d+)" creates a macro that expands to the minor version based on the QT_VER environment variable. A macro that defines a match pattern outputs all capture groups concatenated together, or the exact matched string if the pattern does not contain any capture groups (parentheses). Task-number: QTBUG-67818 Change-Id: I8dd5b08a05555b381d100e30aaef7a9930710993 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
| * Fix crash when expanding macros in sectionsKai Koehne2018-09-061-1/+1
| | | | | | | | | | | | | | | | | | Do not rely on endPos, but instead use the length of the macro already calculated. This amends commit 85bc558660 . Task-number: QTBUG-67818 Change-Id: Icc0268e67eceee83bb5510b5199684c465b2dd56 Reviewed-by: Martin Smith <martin.smith@qt.io>
* | QDoc: Clean up code, old style casts and more 0 nullptr constantsPaul Wicking2018-09-031-134/+134
|/ | | | | Change-Id: I96ff2ba00f419796a8649d5392f7c164579b0d16 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Allow macro expansion in qdoc command argumentsTopi Reinio2018-07-311-37/+56
| | | | | | | | | | | | | | | | | | Until now, QDoc did not expand macros if they were used in arguments for other commands. Macros can be useful in command arguments, for example: \qmlmodule QtQuick 2.\qtminorversion where \qtminorversion expands to the current minor version, or \title \productname Manual where \productname expands to the current product name. Task-number: QTBUG-67818 Change-Id: Ib3e2da9f6bd20343a454f467742cfa00ee09b39a Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Allow escaping of single words to prevent autolinkingMartin Smith2018-06-181-5/+54
| | | | | | | | | | | | | | This update allows the writer to prevent QDoc from automatically making a word into a link. For example, because LayoutMirroring looks like a name that should become a link to something on a type reference page, QDoc finds that reference page and the appropriate section and makes LayoutMirroring be a link to it. By prepending a single '\' to it in the text like this: \LayoutMirroring QDoc does not turn it into a link and just appends LayoutMirroring to the text. Change-Id: Ied7653d1e8f9d56dd5d86d1c16e2aaedf0a88a42 Task-number: QTBUG-20537 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* qdoc: Remove a useless #ifdefMartin Smith2018-02-231-11/+0
| | | | | | | QDOC2_COMPAT is no longer meaningful. Change-Id: I7ba96cef2002ffeaccb333d4938f9f415569850a Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc/webxml: Output resolved snippet pathFriedemann Kleint2018-02-191-4/+17
| | | | | | | | | | | | | | Extract a helper function to resolve snippet files and use it in the WebXML generator to output the resolved snippet path. This can be used by PySide2 to fall back to a C++ snippet in case a matching Python snippet is not present. Task-number: PYSIDE-363 Change-Id: I182ae660227e97edf43e6dac906aeff9a5ae23f9 Reviewed-by: Martin Smith <martin.smith@qt.io> Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io> Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* qdoc/Config::findFile() Make userFriendlyFilePath an optional out parameterv5.11.0-alpha1Friedemann Kleint2018-02-141-1/+1
| | | | | | Task-number: PYSIDE-363 Change-Id: If076c9a77a5a11c05035f6fc30e6d68e60a35045 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Reformat giant switch statement according to Qt Coding StyleMartin Smith2018-01-311-176/+96
| | | | | | | | | This is a WS-only change to correct a lot of indentations, uses of curly braces, and placement of else keywords. It had grown a bit ugly. Change-Id: Ic3c17765e3651738532653eeb653661d46bba35c Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* qdoc: Add optional since clause to \value commandMartin Smith2017-11-151-0/+10
| | | | | | | | | | | | | | | | | | | This update adds the capability to include a since clause in a \value command. Without the since clause, a \value command might look like this: \value QtInfoMsg A message generated by the qInfo() function. The same command with a since clause would look like this: \value [since 5.5] QtInfoMsg A message generated by the qInfo() function. The since clause must be encosed in square brackets and must appear before the value name. Task-number: QTBUG-40782 Change-Id: If6cbb831c6f355eabcb0ddfdc284d2c9453f6245 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Merge remote-tracking branch 'origin/wip/qdoc-clang' into devLiang Qi2017-11-131-123/+102
|\ | | | | | | | | | | | | | | | | Conflicts: src/qdoc/cppcodeparser.h src/qdoc/location.cpp src/qdoc/qmlcodeparser.h Change-Id: I2e579ca5d83cd1c4b42acc9a07066d800cbc02cb
| * qdoc: Remove unnecessary call of location().push()wip/qdoc-clangMartin Smith2017-11-081-1/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The function pushes the file name onto the location stack so that if an error occurs while processing the macro, the error message can contain the correct file location for the macro in error. But this call was pushing the location of the file containing all the macro definitions. If there is an error processing the macro, it should refer to the location where the macro was used, because that's where the error is, not in the macro definition. So the call to push() was wrong to begin with. Besides that, the push was never popped, which led to a fatal qdoc error in macOS. Change-Id: Ib2f74556f6a30a557e79d5c85cd12c8b3077b99a Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
| * qdoc: Remove chapter and part commandsMartin Smith2017-08-101-31/+1
| | | | | | | | | | | | | | | | These commands are not used anywhere, and they cause qdoc to generate illegal html code, so they are removed. Change-Id: I39b670a9691221854a78ea5c332c67ea758199ee Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
| * doc: Fix qdoc macro processingMartin Smith2017-08-101-91/+101
| | | | | | | | | | | | | | | | | | | | qdoc was not replacing qdoc macros correctly. Hopefully, this corrects that bug. It works for the cases I tested. I also changed the name of a class data member from "in" to "input_" so it is easy to search for. Change-Id: I53b8a701efa6b4113173f9d9bb7cf4ebe0a449c4 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* | qdoc: Make doc configuration aware of the output formatTopi Reinio2017-10-171-119/+137
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* Fix GCC 7 warnings about unmarked case statement fallthroughsThiago Macieira2017-06-041-1/+4
| | | | | | | doc.cpp:632:39: error: this statement may fall through [-Werror=implicit-fallthrough=] Change-Id: Ia3e896da908f42939148fffd14c48709a6772552 Reviewed-by: Martin Smith <martin.smith@qt.io>
* qdoc: Improve \brief handlingTopi Reinio2017-02-141-1/+4
| | | | | | | | | | | | | | | | | | | | | There were several issues with how \brief text was generated, especially for C++ properties and variables. This commit changes the \brief generation by: - Preface a brief with 'This property holds ...' only if the produced text is more or less grammatically sound. - Eliminates 'This property holds this property holds' duplicates. - Allow any formatting within a \brief. Previously, input like "\brief \c true" produced no output. The last issue is fixed also for brief attributes written to index files, although there we cannot retain the formatting. In order to do this, the Generator::plainCode() function was made static. Change-Id: If5b3b7e626e87116c3d8d3c1f777d604e4647eb8 Task-number: QTBUG-58280 Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> Reviewed-by: Martin Smith <martin.smith@qt.io>
* Updated license headers and license testsAntti Kokko2016-06-101-17/+12
| | | | | | | | | | | | | From Qt 5.7 -> tools & applications are licensed under GPL v3 with some exceptions, see http://blog.qt.io/blog/2016/01/13/new-agreement-with-the-kde-free-qt-foundation/ Updated license headers to use new GPL-EXCEPT header instead of LGPL21 one (in those files which will be under GPL 3 with exceptions) License header tests also updated to match current headers. Change-Id: Ia6bdacaa3c5bbc9d31334e1a0cabfe502a484dc4 Reviewed-by: Jani Heikkinen <jani.heikkinen@qt.io>
* qdoc: Use '//!' as a documentation commentTopi Reinio2016-04-051-0/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This commit makes QDoc treat a string starting with '//!' as a single-line comment that is not included in the generated HTML output. It has several uses: Internal documentation remarks visible only in the source code, and a simpler alternative to \omit, \endomit commands. Most importantly, it allows \include command to pull in content from any file mentioned in the source directories, for example: /*! \fn foo() //! [foo-descr] ...long description... //! [foo-descr] */ /*/ \fn foo(int bar) \overload foo() \include foo.cpp foo-descr ... */ Above will work and the snippet identifies are omitted from the generated HTML output. Change-Id: I0777247dc00358682c307c356fb7d1d8a4514dac Task-number: QTBUG-52063 Reviewed-by: Martin Smith <martin.smith@theqtcompany.com>
* qdoc: Always remove excess indentation from code snippetsTopi Reinio2015-11-271-5/+1
| | | | | | | | | | | | | | | QDoc kept track of a 'minimum indent' between code snippets seen in the same comment block. If the first snippet had 0 indentation, all other snippets were output with their indentation intact. This change removes the stored minimum indent, causing the least indented line in any <pre> block to never have leading spaces. Has no effect on the indentation within a code snippet. Change-Id: Ie27a4b4d370c545036dfaa573807ba9f59bbdce1 Task-number: QTBUG-49617 Reviewed-by: Martin Smith <martin.smith@theqtcompany.com>
* qdoc: Fix crash with multiple macro parametersTopi Reinio2015-11-241-0/+2
| | | | | | | | | | | | | When the number of parameters expected by a macro definition does not match what's passed to the macro invocation, store the number of parameters read so far. This prevents a crash by out-of-range index reference. Also, improve the documentation on macro parameters. Change-Id: I75716f5b53f394664bb509c96aa4b53b4efba222 Task-number: QTBUG-49608 Reviewed-by: Martin Smith <martin.smith@theqtcompany.com>
* move qdoc back to qttoolsOswald Buddenhagen2015-10-231-0/+3380
we can do that now, as the bootstrap lib is now a properly exported module, and qmldevtools is now bootstrapped as well. this removes the abomination of a copy of the qml parser in qtbase. unfortunately qtbase/2422251ee5025a067b14b989153764ab36e43f10 is reverted, as qtdeclarative is still missing the respective change. this introduces no regression in discoverability or usability, as a full doc build already needed qttools - for qhelpgenerator. Change-Id: Ic9c4c9732ddf5998637b9e42e27939ba50b31479 Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@theqtcompany.com> Reviewed-by: Martin Smith <martin.smith@digia.com> Reviewed-by: Lars Knoll <lars.knoll@theqtcompany.com> Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
View Lorry Controller Status