Mercurial Repositories > eric / file comparison
comparison: eric7/QScintilla/DocstringGenerator/EricdocGenerator.py
eric7/QScintilla/DocstringGenerator/EricdocGenerator.py
- branch
- eric7
- changeset 8312
- 800c432b34c8
- parent 8005
- 94a6a1bd5f80
- child 8881
- 54e42bc2437a
equal
deleted
inserted
replaced
| 8311:4e8b98454baa | 8312:800c432b34c8 |
|---|---|
| 1 # -*- coding: utf-8 -*- | |
| 2 | |
| 3 # Copyright (c) 2021 Detlev Offenbach <detlev@die-offenbachs.de> | |
| 4 # | |
| 5 | |
| 6 """ | |
| 7 Module implementing the docstring generator for the 'ericdoc' style. | |
| 8 """ | |
| 9 | |
| 10 | |
| 11 def generateEricDoc(functionInfo): | |
| 12 """ | |
| 13 Function to generate the docstring line list iaw. eric documentation style. | |
| 14 | |
| 15 Note: Partial English text is created with DESCRIPTION placeholders | |
| 16 for descriptions and TYPE placeholders for type information | |
| 17 | |
| 18 @param functionInfo object containing the function information to base | |
| 19 the docstring on | |
| 20 @type FunctionInfo | |
| 21 @return list of docstring lines | |
| 22 @rtype str | |
| 23 """ | |
| 24 # __IGNORE_WARNING_D202__ | |
| 25 lines = [] | |
| 26 | |
| 27 # create a basic/partial function description | |
| 28 if functionInfo.functionType == "classmethod": | |
| 29 descr = "Class method " | |
| 30 elif functionInfo.functionType == "staticmethod": | |
| 31 descr = "Static method " | |
| 32 elif functionInfo.functionType == "constructor": | |
| 33 descr = "Constructor" | |
| 34 else: | |
| 35 if functionInfo.visibility == "public": | |
| 36 descr = "Public " | |
| 37 elif functionInfo.visibility == "protected": | |
| 38 descr = "Protected " | |
| 39 elif functionInfo.visibility == "private": | |
| 40 descr = "Private " | |
| 41 elif functionInfo.visibility == "special": | |
| 42 descr = "Special " | |
| 43 else: | |
| 44 descr = "" | |
| 45 | |
| 46 if ( | |
| 47 len(functionInfo.argumentsList) > 0 and | |
| 48 functionInfo.argumentsList[0][0] in ("self", "cls", "this") | |
| 49 ): | |
| 50 if functionInfo.isAsync: | |
| 51 descr += "coroutine " | |
| 52 elif functionInfo.functionType == "qtslot": | |
| 53 descr += "slot " | |
| 54 else: | |
| 55 descr += "method " | |
| 56 else: | |
| 57 if functionInfo.isAsync: | |
| 58 descr = "Coroutine " | |
| 59 elif functionInfo.functionType == "qtslot": | |
| 60 descr = "Slot " | |
| 61 else: | |
| 62 descr = "Function " | |
| 63 lines.append(descr) | |
| 64 | |
| 65 # remove 'self', 'this' or 'cls' from arguments list | |
| 66 if ( | |
| 67 len(functionInfo.argumentsList) > 0 and | |
| 68 functionInfo.argumentsList[0][0] in ("self", "cls", "this") | |
| 69 ): | |
| 70 del functionInfo.argumentsList[0] | |
| 71 | |
| 72 # add an empty line if there is one of the other sections | |
| 73 if ( | |
| 74 functionInfo.argumentsList or | |
| 75 functionInfo.hasYield or | |
| 76 functionInfo.returnTypeAnnotated or | |
| 77 functionInfo.returnValueInBody or | |
| 78 functionInfo.raiseList | |
| 79 ): | |
| 80 lines.append("") | |
| 81 | |
| 82 # add the parameters section | |
| 83 tag = "@param" | |
| 84 for argName, argType, argValue in functionInfo.argumentsList: | |
| 85 if argName == "*": | |
| 86 tag = "@keyparam" | |
| 87 continue | |
| 88 | |
| 89 argLine = "{0} {1} DESCRIPTION".format(tag, argName) | |
| 90 if argValue: | |
| 91 argLine += " (defaults to {0})".format(argValue) | |
| 92 lines.append(argLine) | |
| 93 | |
| 94 if argType is None: | |
| 95 argType = "TYPE" | |
| 96 argLine = "@type {0}".format(argType) | |
| 97 if argValue: | |
| 98 argLine += " (optional)" | |
| 99 lines.append(argLine) | |
| 100 | |
| 101 # add return section | |
| 102 if ( | |
| 103 functionInfo.hasYield or | |
| 104 functionInfo.returnValueInBody or | |
| 105 functionInfo.returnTypeAnnotated | |
| 106 ): | |
| 107 if functionInfo.hasYield: | |
| 108 lines.append("@yield DESCRIPTION") | |
| 109 rType = "@ytype" | |
| 110 else: | |
| 111 lines.append("@return DESCRIPTION") | |
| 112 rType = "@rtype" | |
| 113 if functionInfo.returnTypeAnnotated: | |
| 114 lines.append("{0} {1}".format( | |
| 115 rType, functionInfo.returnTypeAnnotated)) | |
| 116 else: | |
| 117 lines.append("{0} TYPE".format(rType)) | |
| 118 | |
| 119 # add an exceptions section, if function raises something | |
| 120 if functionInfo.raiseList: | |
| 121 for exc in sorted(functionInfo.raiseList): | |
| 122 lines.append("@exception {0} DESCRIPTION".format(exc)) | |
| 123 | |
| 124 return lines |
