나는 Linux와 FreeBSD를 위한 작은 C 라이브러리를 작성했으며 이를 문서화할 예정입니다. 매뉴얼 페이지 작성에 대해 더 자세히 알아보려고 했지만 라이브러리용 매뉴얼 페이지 작성에 대한 모범 사례에 대한 지침이나 설명을 찾지 못했습니다. 특히 함수 매뉴얼 페이지의 어느 부분이 배치되어 있는지에 관심이 있습니다. 삼? 어쩌면 좋은 예나 매뉴얼이 있을까요? 라이브러리의 모든 기능에 대해 매뉴얼 페이지를 만드는 것은 나쁜 생각입니까?
답변1
라이브러리의 매뉴얼 페이지는 섹션 3에 배치됩니다.
매뉴얼 페이지의 좋은 예를 보려면 일부 매뉴얼 페이지가 groff의 특정 세부 사항으로 작성되거나 실제로 이식성이 없는 특정 매크로를 사용한다는 점을 명심하십시오.
일부 시스템에서는 특수 기능을 사용할 수도 있고 사용하지 않을 수도 있기 때문에 매뉴얼 페이지 이식성에는 항상 몇 가지 함정이 있습니다. 예를 들어 로깅할 때dialog, 다양한 시스템에서 표시된 예제의 차이점을 기억하고 해결해야 합니다(이는 불합리합니다).
다음으로 시작됨읽다man man표준 매크로의 관련 부분을 언급하고,비교하다이 설명은 FreeBSD 및 Linux에 대한 것입니다.
라이브러리에 대해 하나의 매뉴얼 페이지를 작성하도록 선택하는지 아니면 함수(또는 기능 그룹)에 대해 별도의 매뉴얼 페이지를 작성하도록 선택하는지 여부는 함수 설명의 복잡성에 따라 다릅니다.
추가 자료:
답변2
나는 사용한다론. Markdown을 작성하면 맨페이지로 변환됩니다. 또 하나 있습니다 (약간 능력이 떨어짐)JS그 클론은술래.
나는 항상 END_MAN구분된 heredocs를 사용하여 내 스크립트를 문서화했으며 동일한 END_MAN구분된 heredocs를 사용하여 내 C/C++ 코드를 문서화했습니다(예외 /* */. sed를 사용하여 둘 다 쉽게 추출한 다음 맨페이지로 렌더링할 수 있습니다. (약간의 UNIX 신호 해킹으로) inotifywait를 사용하면 맨페이지 섹션을 실시간으로 추출하고 볼 수 있으며 소스가 업데이트되면 맨페이지 브라우저를 다시 로드할 수 있습니다.
그 부분은 사용자 수준 C 라이브러리의 경우 3입니다. 장 번호에 대해 읽을 수 있습니다(무엇보다도).남자(1).
읽기 쉽고 잘 구성된 예제 매뉴얼 페이지를 보려면 Plan9를 살펴보겠습니다.https://swtch.com/plan9port/unix/제작자와 문서 시스템이 이 작업을 어떻게 c수행했는지 배울 수 있는 라이브러리입니다 .UNIX
답변3
답변4
다음을 사용하여 API를 로깅할 수 있습니다.강력한 산소HTML로 참조를 제공하고 오프라인 읽기를 위한 매뉴얼 페이지와 기타 형식을 생성합니다.
doxygen의 좋은 점은 JavaDoc이나 PythonDoc과 같은 "인라인" 문서라는 것입니다. 이 문서는 소스/헤더 파일에 문서 텍스트를 추가하고 추출합니다. 거기에서 문서 텍스트를 작성하면 최신 상태를 유지할 가능성이 높아집니다.