Sinon: "API 사양"스타일 문서

그건 그렇고, 나는 가치있는 현재 문서에 귀를 기울이지 않습니다. 나는 단지 추가적이고 포괄적 인 것을 제안하는 것입니다.

Java에는 수동 작업없이 JavaDocs를 생성하는 자동 도구가 있습니다. JS 라이브러리에서 이와 같은 것을 얻으려면 많은 수작업이 필요합니다. 나는 그와 같은 것을보고 싶지만 꽤 빨리 구식이 될 것이 두렵다.

우리는 코드 주석과 도구에 대해 약간의 자전거를 탈 수 있습니다. 실행 가능한 옵션이있을 수 있습니다.

나는 그것이 다른 스레드에서 제기되었다는 것을 알고 있지만, 매우 간단하게 전체 라이브러리가 jsDoc으로 문서화되어야한다고 생각합니다. 이것은 JavaScript에 대한 사실상의 표준입니다 (또는 적어도 하나에 대한 가장 강력한 주장). 우리는 최소한의 문서 범위로 시작하여 API를 게시하고 벽에 큰 "진행 중"표시를 놓고 거기에서 빌드 할 수 있습니다.

@mantoni JSDocs 를 자동 생성하기위한 많은 도구가 있습니다. 나는 이것의 v1이 문제라고 보지 않는다. 모든 곳에서 @typedef 를 만들 필요는 없습니다. 그냥 가지고

/**
  <strong i="8">@param</strong> {String} [foo] optional string
  <strong i="9">@example</strong> Create foo instance
       var foo = dooFoo('somestring') 
*/ 

꽤 도움이 될 것입니다.

안녕하세요 @ 76784 , 훌륭한 입력입니다! 😊

그러나 몇 가지 고려해야 할 사항이 있습니다.

나는 JSDoc을 아주 좋아합니다. 그것은 또한 우리가 Chai.js 그리고 그것은 네임 스페이스로 분리 할 수 ​​있고 코드가 서로 바로 옆에 있기 때문에 항상 문서와 동기화를 유지할 수 있기 때문에 지금까지 꽤 잘 작동했습니다.

그러나 Java의 문서가 "골드 표준"이라는 데 동의하지 않습니다. Java 문서가 매우 건조하다고 생각합니다. 참고 용으로는 좋지만 더 큰 부분을 배우거나 groking하는 데는 좋지 않습니다. Sinon의 문서가 친숙한 일반 텍스트 고전 스타일로 작성되었다는 사실이 마음에 듭니다. 채택을 유도하는 IMO. 또한 API 참조로서 그들은 꽤 좋은 IMO입니다.

물론 JSDocs를 사용하는 것이 좋을 것이라고 생각하지만 매우 큰 노력이 필요하다는 사실을 알아 차리는 것이 중요합니다.

@ 76784 가 분기를 시작하고 몇 가지 개념을 구체화하면 아이디어에 끌린 일부 사람들이 신속하게 붙잡고 도움을 줄 수 있다고 생각합니다. API 표면은 그다지 크지 않습니다.

안녕하세요.

Java 문서가 매우 건조하다고 생각합니다. 참고 용으로는 좋지만 더 큰 부분을 배우거나 groking하는 데는 좋지 않습니다.

동의하지 않습니다. 나는 단지 문서와 튜토리얼의 두 가지가 분리되어야한다고 말하는 것입니다. javadocs의 건조 함은 플러스입니다. 하나는 거기에 가서이 드라이어 컨벤션을 통해 "사물"이하는 일을 알아낼 수 있습니다. 물론 가장 중요한 것은 본질적으로 포괄적이라는 것입니다. 나는 내 문서에 장황한 문장 구조를 원하지 않는다-나는 내 튜토리얼에서 그것을 원한다.

저는 JSDoc의 전문가는 아니지만 JSDoc 주석에 항목에 대한 자습서로 연결하는 쉬운 방법이 있는지 궁금합니다.

이것에 대한 개념 증명을 제공하는 것에 관해서는 @ fatso83 현재 시간이 조금 부족합니다 (누가 그렇지 않습니까?).하지만 올해 후반에 더 나은 위치에있을 수 있습니다. . Sinon을 철저히 배우는 좋은 방법이 될 것입니다.

이 문제는 최근 활동이 없었기 때문에 자동으로 오래된 것으로 표시되었습니다. 더 이상 활동이 발생하지 않으면 폐쇄됩니다. 귀하의 기여에 감사드립니다.

이 문제를 고정 했으므로 Stale 봇에 의해 닫히지 않습니다.

이 길로 가기로 결정했다면 https://github.com/gajus/eslint-plugin-jsdoc 와 같은 것을 사용해야한다고 생각합니다 ... 규칙은 아마도 eslint-config-sinon 들어가야합니다.

이것에 뛰어 들고 빠져 나가서 미안합니다-그것은 실제로 일부 작업 우선 순위에 의해 좌우됩니다. 그리고 이것이 올바른 스레드인지 모르겠지만 기존 문서에 대한 더 많은 피드백을 제공하기 위해 ...

스파이와 같은 것을 보면 : https://sinonjs.org/releases/v7.4.1/spies/

나는 첫 번째 청크에 표시된 것과 다른 구문을 가진 Mocha로 작업하고 있습니다.

"test should call subscribers on publish": function () {
    var callback = sinon.spy();
    PubSub.subscribe("message", callback);

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

그것이 무엇이든 (Jasmine?) 대신에 Mocha를 사용하고 있다는 사실은 큰 일이 아닙니다 . 그들은 분명히 유사합니다. 그러나 메이크업을 무엇을 이해하기 어려운 예는 테스트중인 기능을 표시하지 않는 것을.

예를 들어 보려면 그렇게해야한다고 생각합니다. 테스트 대상의 최소 작동 기능을 보여줍니다. myLib 와 동일한 문제 : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

나는 그것을 얻는다- myLib 는 내가 쓸 것이다. 그러나 당신은 많은 초보자들에게 그들이 무엇에 대해 테스트하고 있는지 보지 않고이 것들을 배워야한다고 요구하고 있습니다.

실제로 그 테스트는 Mocha의 구문을 사용하는 것입니다. 당신은 단지 더 표준적인 BDD 스타일을 사용하고 있습니다. 어쨌든 누군가가 모든 예제를 사용중인 가장 일반적인 스타일로 업데이트하는 것이 합리적 일 것입니다. :-)

다른 요점에 관해서는, 이것들은 매우 타당하며 우리가 논의한 것입니다. 실제로 우리는 실행 가능하고 테스트되고 내장 된 예제를 가지고 유효성을 보장하는 것에 대해 논의했습니다. 암시 적으로 이러한 문제를 해결할 것입니다. 하지만 예, 누군가가 앉아서해야합니다 ...

실제로 그 테스트는 Mocha의 구문을 사용합니다.

뭐?? 이제 나는 Mocha 문서에 대해 외쳐야 할 것입니다. :-)

https://github.com/sinonjs/samsam/pull/82 에서이 노력을 시작하려고했습니다