Skip to content

Commit

Permalink
chore: polish docs and comments (#1118)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tangcent
tangcent authored Mar 31, 2024
1 parent abcaae1 commit 71757d0
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 17 deletions.
26 changes: 15 additions & 11 deletions idea-plugin/parts/pluginDescription.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,24 +11,28 @@ <h1>easy-yapi</h1>

<ul>
<li>Parse API documents based on javadoc & KDoc & ScalaDoc</li>
<li>Note that you can get a fairly complete API document in the case of zero intrusion of the code.</li>
<li>However, special requirements still need some special comments/annotations. Compared with this, you can use
flexible configuration rules to adapt to the characteristics of your project to minimize code intrusion.
<li>Note: It's possible to generate a comprehensive API document with minimal code modification.</li>
<li>However, specific requirements might necessitate additional comments/annotations.
To minimize code intrusion, you can employ flexible configuration rules tailored to your project's needs.
</li>
</ul>
<br/>
<b> Refer to <a href="[https://easyyapi.com ↗](https://easyyapi.com)">Guide</a> for details</b>
<b> For more details, refer to the <a href="[https://easyyapi.com ↗](https://easyyapi.com)">Guide</a></b>

<ul>Export API to Yapi/Postman/Markdown:
<p> Open the file containing <code>api</code> in the project or select the file or folder in the IDE's left project
file area, use the shortcut <kbd>Alt</kbd> <kbd>Shift</kbd> <kbd>E</kbd> (windows) / <kbd>Ctrl</kbd> <kbd>E</kbd> (mac), Then
select the API you want to export, select the export channel <code>Yapi/Markdown/Postman</code>, Click the [✔]
button or press Enter to complete the export.
<ul>How to Export API to Yapi/Postman/Markdown:
<p>
In your project, open the file containing the <code>API</code> or select the desired file or folder in the IDE's
left project file area.
</p>
<p>
Use the shortcut <kbd>Alt</kbd> <kbd>Shift</kbd> <kbd>E</kbd> (windows) / <kbd>Ctrl</kbd> <kbd>E</kbd> (mac).
Then, select the APIs you want to export, select the export channel <code>Yapi/Markdown/Postman</code>,
and click the [✔] button or press Enter to complete the export.
</p>
</ul>
<br/>
<p>
If the shortcut is invalid, please check for shortcut conflicts. You can modify the
shortcut in <kbd>Preferences(Settings)</kbd> > <kbd>KeyMap</kbd>.
<b>Note:</b> If the shortcut does not work, check for shortcut conflicts.
You can modify the shortcut in <kbd>Preferences(Settings)</kbd> > <kbd>KeyMap</kbd>.
</p>
<br/>
46 changes: 40 additions & 6 deletions idea-plugin/src/main/kotlin/com/itangcent/idea/plugin/api/DefaultMethodInferHelper.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ import java.lang.reflect.Modifier
import java.util.*

/**
*1.Try infer the return type of method
*It should be called from the UI thread
* Handles inferring the return type of methods
* It should be executed within the UI thread.
*/
@Singleton
class DefaultMethodInferHelper : MethodInferHelper {
Expand Down Expand Up @@ -58,18 +58,26 @@ class DefaultMethodInferHelper : MethodInferHelper {
@Inject
protected lateinit var intelligentSettingsHelper: IntelligentSettingsHelper

//Cache for storing the results of static method invocations to avoid recomputation.
private val staticMethodCache: HashMap<Pair<PsiMethod, Array<Any?>?>, Any?> = HashMap()

//Tracks the current stack of method inferences to avoid infinite recursion.
private val methodStack: Stack<Infer> = Stack()

//JSON options for controlling the serialization behavior in the inference process.
private var jsonOption: Int = JsonOption.ALL

private var simpleJsonOption: Int = jsonOption and JsonOption.READ_GETTER.inv()

//Limits the depth of object graph exploration to prevent excessively deep or infinite recursion.
private var maxObjectDeep: Int = 4

//A cache for methods that do not require arguments to infer their return types.
private val emptyCallMethodCache: HashMap<PsiMethod, Any?> = HashMap()

/**
* Main methods for inferring the return type of a given PsiMethod.
*/
override fun inferReturn(psiMethod: PsiMethod, option: Int): Any? {
return emptyCallMethodCache.safeComputeIfAbsent(psiMethod) {
return@safeComputeIfAbsent inferReturn(psiMethod, null, null, option)
Expand Down Expand Up @@ -123,6 +131,9 @@ class DefaultMethodInferHelper : MethodInferHelper {
return DirectVariable { psiClassHelper!!.getTypeObject(psiMethod.returnType, psiMethod, jsonOption) }
}

/**
* Cleans up the inferred return values by removing invalid keys, based on predefined criteria.
*/
private fun Any?.cleanInvalidKeys(): Any? {
when (this) {
null -> return null
Expand Down Expand Up @@ -165,6 +176,10 @@ class DefaultMethodInferHelper : MethodInferHelper {

}

/**
* Computes a "point" score for an object based on its complexity and contents.
* This score helps in prioritizing more informative or complex inferred values.
*/
private fun pointOf(obj: Any?): Int {
when (obj) {
null -> return 0
Expand Down Expand Up @@ -207,7 +222,9 @@ class DefaultMethodInferHelper : MethodInferHelper {
}

/**
* Try a simple call
* Attempts a simple method call based on static analysis and predefined patterns,
* like getter/setter methods, to quickly infer the return type without deep analysis.
* e.g.
* static method
* getter/setter
* method of collection(Set/List/Map...)
Expand Down Expand Up @@ -306,6 +323,11 @@ class DefaultMethodInferHelper : MethodInferHelper {
return CALL_FAILED
}

/**
* Handles the inference process when the simple approach fails. This method
* performs a more detailed analysis, potentially involving recursive inference,
* to determine the method's return type.
*/
private fun inferReturnUnsafely(psiMethod: PsiMethod, caller: Any? = null, args: Array<Any?>?, option: Int): Any? {
actionContext!!.checkStatus()
val realCaller = valueOf(caller)
Expand All @@ -314,7 +336,7 @@ class DefaultMethodInferHelper : MethodInferHelper {
if (allowQuickCall(option)) {
try {
return tryInfer(QuicklyMethodReturnInfer(psiMethod, this))
} catch (e: Exception) {
} catch (_: Exception) {
}
}

Expand Down Expand Up @@ -526,11 +548,15 @@ class DefaultMethodInferHelper : MethodInferHelper {

const val DEFAULT_OPTION = ALLOW_QUICK_CALL

//Determines if a method allows for quick call-based inference.
fun allowQuickCall(option: Int): Boolean {
return (option and ALLOW_QUICK_CALL) != 0
}

//Static failure object used to signal that a method call cannot be inferred.
private val CALL_FAILED = Any()

//A set of method names considered for quick invocation without deep analysis.
private val COLLECTION_METHODS = setOf("put", "set", "add", "addAll", "putAll")

private fun isSuperMethod(method: PsiMethod, superMethod: PsiMethod): Boolean {
Expand Down Expand Up @@ -883,6 +909,11 @@ class DefaultMethodInferHelper : MethodInferHelper {
}
}

/*
* Defines the contract for inference strategies, allowing different approaches
* to be implemented and utilized based on the context and needs of the inference
* process.
*/
interface Infer {
fun infer(): Any?

Expand All @@ -891,6 +922,11 @@ class DefaultMethodInferHelper : MethodInferHelper {
fun callMethod(): Any?
}

/**
* Abstract implementation of an inference strategy, providing common functionality
* and utilities for handling method return inference. This includes managing local
* variables, processing PSI elements, and handling control flow constructs.
*/
abstract class AbstractMethodReturnInfer(
var caller: Any? = null,
val args: Array<Any?>?,
Expand All @@ -905,8 +941,6 @@ class DefaultMethodInferHelper : MethodInferHelper {

private var inits: HashSet<String> = HashSet()

// val psiClassHelper = ActionContext.getContext()!!.instance(PsiClassHelper::class)

protected open fun processStatement(statement: PsiStatement): Any? {

when (statement) {
Expand Down

0 comments on commit 71757d0

Please sign in to comment.