Critical Gaps in Key Class Implementations (e.g., Order Generation, Trading Parameters)

[Lixuyizhi]

📖 Documentation

​​Problem Summary​​

The current documentation（ version of official documentation（v0.8.6.99）the actual qlib version（v0.9.7）） lacks crucial details for core classes like WeightStrategyBase, forcing users to read the source code to understand fundamental logic. Key parameters, their expected types, and behavioral impacts are either missing or ambiguous, leading to implementation errors and unexpected results.

​​Critical Gaps & Suggested Improvements​​

Gap Category	Specific Issue & Impact	Suggested Improvement
​​Order Generation Logic​​	The default order generator for WeightStrategyBaseis OrderGenWOInteract. Its alternative, OrderGenWInteract, automatically normalizes weights based on ​​tradable​​ stocks, which is vital for full capital utilization but is not mentioned in the docs. Users might unknowingly use a non-capital-efficient method.	Explicitly document the order generators associated with base classes and explain the core difference: whether weight normalization considers dynamic tradability (e.g., suspension, liquidity).
​​Parameter Types & Logic​​	The limit_thresholdparameter for handling price limits is ambiguous. The docs don't clarify that passing a ​​float​​ (e.g., 0.1) sets a static threshold, while a ​​tuple​​ uses an expression. The internal conversion of the expression's result to a bool for decision-making is undocumented and unintuitive.	Clearly document parameter types (float vs. tuple/expression) with examples. Explain the internal logic for expression evaluation and how it triggers the limit logic.
​​Mandatory Fields​​	The necessity of the factorfield for achieving round-lot (integer) trading is not stated. Without it, orders might be generated in fractional shares, causing execution failures in simulations that require integer units.	Add a note in the strategy or executor section stating that the factorfield (often representing a lot size multiplier) is required for integer-share order generation.

​​Proposed Solution​​

Enhance the API reference for critical classes (WeightStrategyBase, OrderGenWInteract, etc.) with:

1. ​​Detailed behavioral descriptions​​ of key methods and their dependencies.

2. ​​Clear parameter specifications​​, including expected data types and practical effects.

3. ​​Concrete code snippets​​ showing proper usage, especially for complex parameters like limit_threshold.

This will significantly reduce the learning curve and prevent costly errors during strategy development.