Azure / Azure/azure-sdk-tools

[Javascript APIView] Inline object type formatting for method parameters is misleading

Open
#14,369 0 comments 0 reactions 0 assignees View on GitHub
APIView customer-reported Javascript question
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
144

Description

**Bad code snippet:**
```javascript
toJSON(options?: { preserveCase?: boolean; }): RawHttpHeaders;
```

**Issue:**
APIView renders the method parameter's object type inline, which can be misleading for larger or more complex option objects. This formatting is a result of APIView's rendering, not a guideline or code issue. For improved readability, especially as more properties are added, a multi-line format should be used.

**Good code snippet:**
```javascript
toJSON(
options?: {
preserveCase?: boolean;
// additional properties here
}
): RawHttpHeaders;
```

APIView should render object types for method parameters in a multi-line format when the object is or may become complex, to improve readability.

Contributor guide

Open the contributing guide

Research direction

The issue concerns APIView rendering of JavaScript method-parameter object types; start by locating the APIView parser or renderer entry point for this formatting and compare the bad and good snippets. Done means complex object parameters render across multiple lines without changing the API signature.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.