315 lines
6.9 KiB
Markdown
315 lines
6.9 KiB
Markdown
# Signature Analysis Methodology
|
|
|
|
This guide provides methodology for extracting and documenting function, method, and interface signatures at the C4 Code level.
|
|
|
|
---
|
|
|
|
## Parameter Extraction
|
|
|
|
### Required Information
|
|
|
|
For each parameter, extract:
|
|
|
|
| Field | Description | Example |
|
|
|-------|-------------|---------|
|
|
| `name` | Parameter name (original case) | `userId`, `options` |
|
|
| `type` | Full type including generics | `string`, `UserOptions<T>` |
|
|
| `optional` | Whether parameter is optional | `true`, `false` |
|
|
| `default` | Default value if any | `{}`, `null`, `10` |
|
|
|
|
### TypeScript Examples
|
|
|
|
```typescript
|
|
// Required parameter
|
|
function getUser(userId: string) { }
|
|
// → { name: "userId", type: "string", optional: false }
|
|
|
|
// Optional parameter
|
|
function getUser(userId: string, includeDeleted?: boolean) { }
|
|
// → { name: "includeDeleted", type: "boolean", optional: true }
|
|
|
|
// Default parameter
|
|
function getUsers(limit: number = 10) { }
|
|
// → { name: "limit", type: "number", optional: true, default: "10" }
|
|
|
|
// Generic parameter
|
|
function transform<T>(input: T[]): T { }
|
|
// → { name: "input", type: "T[]", optional: false }
|
|
|
|
// Object destructuring
|
|
function create({ name, age }: UserInput) { }
|
|
// → { name: "{ name, age }", type: "UserInput", optional: false }
|
|
|
|
// Rest parameters
|
|
function concat(...items: string[]) { }
|
|
// → { name: "...items", type: "string[]", optional: false }
|
|
```
|
|
|
|
### Python Examples
|
|
|
|
```python
|
|
# Required parameter
|
|
def get_user(user_id: str) -> User:
|
|
# → { name: "user_id", type: "str", optional: false }
|
|
|
|
# Optional parameter (with default)
|
|
def get_users(limit: int = 10) -> List[User]:
|
|
# → { name: "limit", type: "int", optional: true, default: "10" }
|
|
|
|
# Optional type hint
|
|
def find_user(user_id: Optional[str]) -> Optional[User]:
|
|
# → { name: "user_id", type: "Optional[str]", optional: false }
|
|
|
|
# *args and **kwargs
|
|
def call_api(*args, **kwargs):
|
|
# → { name: "*args", type: "Any", optional: true }
|
|
# → { name: "**kwargs", type: "Any", optional: true }
|
|
```
|
|
|
|
---
|
|
|
|
## Return Type Analysis
|
|
|
|
### TypeScript Return Types
|
|
|
|
```typescript
|
|
// Simple return
|
|
function getName(): string { }
|
|
// → return_type: "string"
|
|
|
|
// Promise return (async)
|
|
async function getUser(): Promise<User> { }
|
|
// → return_type: "Promise<User>", async: true
|
|
|
|
// Void return
|
|
function logMessage(msg: string): void { }
|
|
// → return_type: "void"
|
|
|
|
// Union return
|
|
function find(): User | null { }
|
|
// → return_type: "User | null"
|
|
|
|
// Generic return
|
|
function first<T>(arr: T[]): T | undefined { }
|
|
// → return_type: "T | undefined"
|
|
|
|
// No explicit return (inferred)
|
|
function calculate() { return 42; }
|
|
// → return_type: "number" (inferred)
|
|
```
|
|
|
|
### Python Return Types
|
|
|
|
```python
|
|
# Simple return
|
|
def get_name() -> str:
|
|
# → return_type: "str"
|
|
|
|
# Optional return
|
|
def find_user() -> Optional[User]:
|
|
# → return_type: "Optional[User]"
|
|
|
|
# Async return
|
|
async def get_user() -> User:
|
|
# → return_type: "User", async: true
|
|
|
|
# No return type (None)
|
|
def log_message(msg: str) -> None:
|
|
# → return_type: "None"
|
|
```
|
|
|
|
---
|
|
|
|
## Async Detection
|
|
|
|
### Patterns to Detect
|
|
|
|
| Language | Pattern | Example |
|
|
|----------|---------|---------|
|
|
| TypeScript | `async` keyword | `async function fetchData()` |
|
|
| TypeScript | Returns `Promise<T>` | `function fetch(): Promise<Data>` |
|
|
| Python | `async def` | `async def fetch_data():` |
|
|
| Java | Returns `CompletableFuture<T>` | `CompletableFuture<Data> fetchData()` |
|
|
|
|
### Examples
|
|
|
|
```typescript
|
|
// Explicit async
|
|
async function fetchUser(id: string): Promise<User> { }
|
|
// → async: true, return_type: "Promise<User>"
|
|
|
|
// Returns Promise but not async keyword
|
|
function fetchUser(id: string): Promise<User> {
|
|
return fetch(`/users/${id}`).then(r => r.json());
|
|
}
|
|
// → async: false, return_type: "Promise<User>"
|
|
```
|
|
|
|
---
|
|
|
|
## Generic Type Parameters
|
|
|
|
### Extracting Generics
|
|
|
|
```typescript
|
|
// Single generic
|
|
function identity<T>(value: T): T { }
|
|
// → generic_params: ["T"]
|
|
|
|
// Multiple generics
|
|
function map<T, U>(arr: T[], fn: (item: T) => U): U[] { }
|
|
// → generic_params: ["T", "U"]
|
|
|
|
// Constrained generic
|
|
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { }
|
|
// → generic_params: ["T", "K extends keyof T"]
|
|
|
|
// Default generic
|
|
function createArray<T = string>(length: number): T[] { }
|
|
// → generic_params: ["T = string"]
|
|
```
|
|
|
|
### Python Generics
|
|
|
|
```python
|
|
from typing import TypeVar, Generic
|
|
|
|
T = TypeVar('T')
|
|
|
|
def identity(value: T) -> T:
|
|
return value
|
|
# → generic_params: ["T"]
|
|
|
|
class Container(Generic[T]):
|
|
def get(self) -> T: ...
|
|
# → generic_params: ["T"]
|
|
```
|
|
|
|
---
|
|
|
|
## Decorator Extraction
|
|
|
|
### TypeScript/JavaScript Decorators
|
|
|
|
```typescript
|
|
@Injectable()
|
|
@Singleton()
|
|
class UserService { }
|
|
// → decorators: ["@Injectable()", "@Singleton()"]
|
|
|
|
@Get('/users/:id')
|
|
@UseGuards(AuthGuard)
|
|
async getUser(@Param('id') id: string) { }
|
|
// → decorators: ["@Get('/users/:id')", "@UseGuards(AuthGuard)"]
|
|
```
|
|
|
|
### Python Decorators
|
|
|
|
```python
|
|
@classmethod
|
|
def from_dict(cls, data: dict) -> 'User':
|
|
# → decorators: ["@classmethod"]
|
|
|
|
@staticmethod
|
|
def validate(data: dict) -> bool:
|
|
# → decorators: ["@staticmethod"]
|
|
|
|
@property
|
|
def full_name(self) -> str:
|
|
# → decorators: ["@property"]
|
|
|
|
@app.route('/users/<id>')
|
|
@require_auth
|
|
def get_user(id: str):
|
|
# → decorators: ["@app.route('/users/<id>')", "@require_auth"]
|
|
```
|
|
|
|
### Java Annotations
|
|
|
|
```java
|
|
@Override
|
|
public String toString() { }
|
|
// → decorators: ["@Override"]
|
|
|
|
@GetMapping("/users/{id}")
|
|
@PreAuthorize("hasRole('USER')")
|
|
public User getUser(@PathVariable String id) { }
|
|
// → decorators: ["@GetMapping(\"/users/{id}\")", "@PreAuthorize(\"hasRole('USER')\")"]
|
|
```
|
|
|
|
---
|
|
|
|
## Visibility Modifiers
|
|
|
|
### TypeScript/JavaScript
|
|
|
|
| Modifier | Visibility |
|
|
|----------|------------|
|
|
| `public` | public |
|
|
| `private` | private |
|
|
| `protected` | protected |
|
|
| `#field` (private field) | private |
|
|
| (no modifier) | public |
|
|
|
|
### Python
|
|
|
|
| Pattern | Visibility |
|
|
|---------|------------|
|
|
| `_method` | internal (convention) |
|
|
| `__method` | private (name mangling) |
|
|
| (no prefix) | public |
|
|
|
|
### Java
|
|
|
|
| Modifier | Visibility |
|
|
|----------|------------|
|
|
| `public` | public |
|
|
| `private` | private |
|
|
| `protected` | protected |
|
|
| (package-private) | internal |
|
|
|
|
---
|
|
|
|
## Complete Signature Example
|
|
|
|
```json
|
|
{
|
|
"signature": {
|
|
"parameters": [
|
|
{
|
|
"name": "userId",
|
|
"type": "string",
|
|
"optional": false
|
|
},
|
|
{
|
|
"name": "options",
|
|
"type": "GetUserOptions",
|
|
"optional": true,
|
|
"default": "{}"
|
|
}
|
|
],
|
|
"return_type": "Promise<User>",
|
|
"async": true,
|
|
"generic_params": []
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### ✅ DO:
|
|
- Extract full type information including generics
|
|
- Note optional parameters and defaults
|
|
- Identify async functions correctly
|
|
- Preserve exact decorator syntax
|
|
- Document visibility modifiers
|
|
|
|
### ❌ DON'T:
|
|
- Skip type information
|
|
- Ignore generic parameters
|
|
- Miss async/Promise patterns
|
|
- Forget decorators that indicate behavior
|
|
- Assume visibility without checking
|