VSCode: Jak dokumentować obietnicę rozwiązującą złożony obiekt?

Question

Mam funkcję f, która zwraca Promise. Zwrócony Promise albo albo albo .

Próbowałem następującą składnię (jak wspomniano w an issue in JSDoc) w VSCode, ale to nie działa:

/** 
* @promise fPromise 
* @reject {Error} 
* @fulfill {Object} project 
* @fulfill {Object} project.data 
* @fulfill {String} project.name 
* @returns fPromise 
*/ 

Answer 1

Myślę, że najlepiej jest owinąć swoją odpowiedź do niestandardowego obiektu fulfill:

/** 
* @promise fPromise 
* @reject {Error} 
* @fulfill {Project} 
* @returns {Promise.<Project>} 
*/ 
function renderResults(data) { 
    return new Promise((resolve, reject) => { 
     resolve(new Project()) 
    }) 
} 

renderResults() 

function Project() { 
    this.data = "data"; 
    this.name = "project phoenix" 
    this.location = { 
     city: 'seattle', 
     state: 'wa' 
    } 
} 

To pokaże w Kodeksie VS tak:

Answer 2

Aby być jak najdalej, dlaczego nie umieścić na charakter obiektu na pojedyncza linia do opisu? To ma być opis tego, co się spełnia.

/** 
* @promise fPromise 
* @fulfill {Object} A project object with the format {name: String, data: Object} 
* @reject {Error} 
* @returns fPromise 
*/ 

Albo, jeśli chcesz obsługiwać dynamicznie generowanych kluczy obiektu, podobne do Google Style Guide:

/** 
* @promise fPromise 
* @fulfill {Object.<String, Object>} 
* @reject {Error} 
* @returns fPromise 
*/ 

który pozwala każdemu czytania komentarz do zrozumienia co zwrócony obiekt wygląda, jakie klawisze są i jaki rodzaj wartości powinien znajdować się w każdym kluczu.

Chyba że, próbujesz powiedzieć, że może on zwrócić jedną z trzech możliwości. Wtedy myślę, że twój oryginalny format jest nieco bardziej opisowy dla możliwych rezultatów spełnienia obietnicy.