문서화 된 JavaScript 함수에 대한 Github 친화적 마크 다운을 쉽게 만드는 방법은 무엇입니까?

문서화 된 JavaScript 함수에 대한 Github 친화적 마크 다운을 쉽게 만드는 방법은 무엇입니까?

---

JavaScript 소스의 어느 곳에서나 이와 같은 JSDoc 주석을 사용할 수 있기를 원합니다 (모듈 또는 익명 함수에서 여러 계층의 함수에 중첩 됨).

/**
 *  Used to do some important thing that needs doing that works like xyz.
 *  @param {String} whatever - some string that has some purpose
 *  @param {Function} callback - a function that needs to be run
 *  @returns {Boolean} whether or not something happened
 */
 function something(whatever, callback) {
     ...

좋은 마크 다운을 생성하는 쉬운 방법이 있습니다.

##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.

*Parameters*
  `whatever {String}` some string that has some purpose
  `callback {Function}` a function that needs to be run

*Returns*
   `{Boolean}` whether or not something happened

여기서 "root"는 해당 함수에 도달 할 수있는 네임 스페이스입니다. 또는 익명 함수 또는 개인 함수 (어떤 이유로 public doco에 있어야하는데 의미가 있나요 ??) 인 경우 다른 규칙을 사용하여이를 나타냅니다. 아마도

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

정확히 그 형식 일 필요는 없으며 Github에서보기 좋고 의미있는 형식 일뿐입니다. 이상적인 도구는 Mustache.js 와 같은 코드를 가져와 좋은 출력을 생성 할 수있을만큼 똑똑 할 것 입니다. 그리고 많은 소스 파일을 처리하고 하나의 문서를 출력으로 생성하거나 구성에 따라 링크 된 문서 세트를 생성 할 수 있다면 더욱 좋습니다.

그리고 이것이 git repo에 완전하고 쉽게 포함될 수있는 방식으로 수행되어 사람들이 doco를 업데이트하기 위해 매우 구체적인 툴체인을 설정할 필요가 없도록하는 것이 가장 좋습니다. 또는 최소한 최소한의 도구 모음이 필요합니다.

아, 그리고 조랑말.

---

기존 옵션

JSDoc 및 일종의 HTML-> 마크 다운 변환

JSDoc은 꽤 좋습니다. 하지만 모듈에서 잘 작동하도록 만들 수없는 것 같습니다. 또는 오히려 IMHO가되어야하는 것보다 더 큰 번거 로움입니다. 함수 이름을 지정하기 위해 추가 태그를 추가 할 필요가 없습니다. @export 및 @name을 시도했지만 원하는 방식으로 최종 문서에 표시하는 데 여전히 문제가 있습니다. 누군가 모듈이 있고 잘 수행되는 JSDoc 주석 소스를 가리킬 수 있다면 도움이 될 수 있습니다. 업데이트 : JSDoc v3는 실제로 v2보다 모듈에서 훨씬 좋아 보이므로 더 적합 할 수 있습니다.

원하는대로 JSDoc 출력을 얻을 수 있더라도 HTML에서 마크 다운으로 변환해야합니다. 좋은 도구를 찾을 수없는 것 같습니다. 하나가 있습니까?

Docdown

나는 Docdown으로 조금 놀았지만 PHP라는 사실은 나를 위해 비스타 터입니다 ...

YUIDoc 및 변환

나는 실제로 YUIDoc을 가지고 놀지 않았지만 괜찮아 보입니다. 그래도 변환기가 필요합니다. 모듈을 쉽게 처리하고 함수 이름을 제공하고 이름을 명시 적으로 내보낼 필요가 없습니까?

Dox 및 마크 다운 템플릿

Dox는 JSON을 출력으로 생성하므로이를 좋은 마크 다운 템플릿과 결합하고 문서를 생성하기위한 템플릿 엔진을 포함해야합니다. 이러한 템플릿 세트를 유용한 방식으로 모은 사람이 있습니까?

jGrouse , 플러스 변환

ANT와 함께 실행됩니다. 다음...

ScriptDoc ...

더 이상 존재합니까? Aptana 스튜디오의 일부인 것 같아서 비스타 터가 될 것입니다 ... Aptana는 그것에 대한 정보가없는 것 같습니다. 하지만 ScriptDoc.org에 크랙에 대한 흥미로운 정보가 있습니다. 도움이된다면 ...

Pdoc

Pdoc은 Ruby 기반이지만 그 툴체인은 드물지 않으므로 큰 문제는 아닙니다. 자신 만의 템플릿을 제공 할 수 있으므로 이미 좋은 마크 다운 템플릿이있을 수 있습니다. 나는 그것을 가지고 놀지 않았다 ... 그만한 가치가 있는가? 좋은 마크 다운 템플릿이 있습니까?

다른 것?

거기에 또 뭐가 있습니까?

당신만의 것을 만드세요!

내가 원하는대로 작동하도록 몇 시간 동안 JSDoc을 엉망으로 만든 후, 나는 포기하고 내가 작업해온 유니 코드 JavaScript 라이브러리 인 CharFunk 용 Java 로 빠르고 더러운 솔루션 을 작성 했습니다. 아직 범용에 가깝지는 않지만 필요한 것을 위해 충분히 작동합니다.

---

그래서.....

충족되지 않은 욕구입니까, 아니면 나뿐입니까?

---

jsdox 를 사용해 보셨습니까 ?

markdown 생성기에 대한 node.js jsdoc입니다.

---

I use jsdoc-to-markdown..

write documented code:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

get markdown docs:

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

These projects have readme files rendered by jsdoc2md:

• handbrake-js
• array-tools
• command-line-args

---

markdox can generate markdown documents from javascript code.

---

jsDox. https://github.com/sutoiku/jsdox Full parse using UglifyJS

Mox. https://github.com/tjchaplin/mox Several ready-to-run examples/templates.

Both handle JSDoc/Dox formats. Both have active development. For me, Mox wins because of the example suite.

---

OK. After some deliberation with myself, I'd go with DOX + Underscore/Whatever JS templating engine over Node.

Should be pretty simple. You can, possibly, even jam into Grunt or similar and have it ran under a watch task.

Dox is, from what I can recall, is relatively lightweight and has an npm package (IIRC).

UPDATE: I think, after some experience, that I'd like to change my answer to YUIDoc.

---

Try using Verb. In the simplest use case Verb will build a readme from a template using data from package.json.

But verb also has advanced features if you need to generate multi-page TOCs, or create custom helpers, etc.

Regarding API documentation, see this example readme generated using code comments from index.js. Click on the headings, those are auto-generated too. Use this built-in helper to generate API docs from whatever file path is specified. You can also use glob patterns to pull in docs from multiple files.

Verb will build a .verb.md without any config. But if you need more, you can use a verbfile.js

---

I had the need of creating a API documentation out of JSDoc which should be easy to use and also supports modern frontend stacks. Some of the mentioned libraries have issues with JS code transpiled into babeljs therefore you have to transpile your code with comments temporarily just to generate your markdown documentation.

For such use case I found http://documentation.js.org/ quite useful as they have integrated support for BabelJs configurations so it takes care of generating markdown (JSON, HTML) from your JSDocs.

참고URL : https://stackoverflow.com/questions/15694267/how-to-easily-create-github-friendly-markdown-for-documented-javascript-function