MQL5 코드용 자동 생성 설명서

1. 개요

대부분의 Java 코더는 JavaDocs로 작성할 수 있는 자동 생성된 문서에 익숙합니다. 이 아이디어는 코드에 주석을 반구조적인 방식으로 추가한 후 쉽게 탐색할 수 있는 도움말 파일로 추출하는 것입니다.

또한 C++ 월드에는 Microsoft의 SandCastle과 Doxygen이 두 선두 업체인 수많은 문서 자동 생성기가 있습니다. Doxygen이 MQL5를 얼마나 잘 문서화할 수 있는지 알아보기로 했습니다. MQL5는 본질적으로 C++의 맞춤형 하위 집합입니다. 저에게 이것은 MQL5의 성숙도에 있어 중요한 단계입니다. 왜냐하면 언어의 복잡성은 쉽게 몇몇 꽤 큰 클래스 라이브러리를 육성할 수 있기 때문입니다.

실험은 매우 잘 진행되었고 Doxygen이 MQL5 코드로 제작한 도움말 문서는 많은 가치를 추가할 것이라고 생각합니다.

2. Doxygen

Doxygen은 GNU General Public License에서 사용할 수 있는 오픈 소스 자동 문서 생성기로, 개발은 Linux 및 Mozilla와 같은 다른 오픈 소스 프로젝트와 유사했습니다. Doxygen은 다운로드와 사용이 자유롭고, 소스 코드는 누구나 볼 수 있으며, 개발되어 시간을 기부하는 다수의 개발자 간의 협업으로 강화되고 있습니다.

Doxygen은 가장 기본적인 사용 수준에서 프로젝트의 모든 C++(또는 MQL5) 코드를 구문 분석하고 해당 구조를 탐색하기 쉬운 도움말 파일로 표시합니다. 이것은 특히 광범위한 클래스 계층과 많은 멤버 함수를 갖는 경향이 있는 Object Oriented 코드 집합에서 유용합니다. Doxygen 기능을 완전히 사용하려면 Doxygen이 이를 읽고 생성된 도움말 파일에 정보를 추가할 수 있도록 구성된 설명도 코드에 기록해야 합니다.

2.1 Doxygen을 다운로드

Doxygen 홈페이지 http://www.doxygen.org/. 여기서 download page 로 이동하여 Windows용 최신 버전을 다운로드할 수 있습니다. 작성 당시 이는 doxygen-1.6.1이었습니다(아래 참조).

그림 1. Doxygen 다운로드

2.2 Doxygen을 구성하고 실행

*.mqh 및 *.mq5 파일 형식을 추가하고 HTML 도움말 생성을 켜는 것 외에는 별다른 작업이 필요하지 않습니다. 다음 5개의 그림이 구성을 통해 실행됩니다.

처음 4개의 스크린샷(그림 2 ~ 5)이 마법사 화면에서 실행됩니다.

그림 2. Doxygen 구성 - 마법사 1

그림 3. Doxygen 구성 - 마법사 2

그림 4. Doxygen 구성 - 마법사 3

그림 5. Doxygen 구성 - 마법사 4

마지막으로, mqh 및 mq5 파일 형식을 추가하는 전문가 수준 변경이 있습니다.

그림 6. Doxygen 구성 - mqh 및 mq5 파일 포함

이제 실행할 준비가 되었습니다. Doxgyen은 구성 파일에 저장하고 읽게 되고, 이 문서의 zip 첨부 파일에 포함되어 있습니다.

그림 7. Doxygen 실행

2.3 Doxygen 실행

Doxygen은 우수한 컴파일된 html 도움말 파일을 가지고 있습니다. (물론 Doxygen과 함께 구성됩니다 - 이것은 오리지널 html 버전입니다.) 이것은 복잡한 수학 공식의 완벽한 표시를 포함한 문서 기능들의 놀라운 배열을 자세히 설명합니다. 그러나 도구를 매우 간단한 방법으로 효과적으로 사용하여 유용한 도움말 파일을 만들 수도 있습니다.

여기 예시가 있습니다. CiMACD::Create() function in MQL5/Include/Oscilators.mqh. 이러한 표시기 파일은 원래 초기 베타 배포의 일부가 아니므로 MetaTrader 5를 다시 다운로드해야 볼 수 있습니다.

//+------------------------------------------------------------------+
//| Create indicator "Moving Averages Convergence-Divergence".       |
//| INPUT:  symbol          -chart symbol,                           |
//|         period          -chart period,                           |
//|         fast_ema_period -period fast EMA,                        |
//|         slow_ema_period -period slow EMA,                        |
//|         signal_period   -period signal MA,                       |
//|         applied         -what used.                              |
//| OUTPUT: true-if successful, false otherwise.                     |
//| REMARK: no.                                                      |
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

키워드에 대한 일부 간단한 변경은 Doxygen의 해석을 위한 주석을 준비합니다. 코멘트는 트리플-슬래쉬 (///), 입력: 변경됩니다 \param, 그리고 출력: 은 \return

//+------------------------------------------------------------------+
/// Create indicator "Moving Averages Convergence-Divergence".        
/// \param  symbol          -chart symbol,                            
/// \param  period          -chart period,                            
/// \param  fast_ema_period -period fast EMA,                         
/// \param  slow_ema_period -period slow EMA,                         
/// \param  signal_period   -period signal MA,                        
/// \param  applied         -what used.                               
/// \return true-if successful, false otherwise.                      
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

Doxygen이 처리했을 때 도움말 파일은 그림 8과 같습니다.

그림 8. Doxygen-generated HTML에 보여지는 CiMACD::Create()

2.4 전체 분산 MQL5 코드 집합에 Doxygen을 사용합니다.

Doxygen의 가장 강력한 기능은 대규모 프로젝트를 위한 도움말 파일을 만드는 것입니다. MQL5 폴더 아래에 MetaTrader 5와 함께 배포되는 파일에는 100개 이상의 .mq5 및 .mqh 파일이 있으며, 이 파일 중 대부분은 상호 연관되어 있습니다.

위에 설명된 Doxygen 주석 변환에 대한 기본 메타 인용을 수행하는 유틸리티 스크립트 MetaquotesCommentsToDoxygen.mq5 (첨부된 zip 파일에 포함)를 작성했습니다. 이 단계는 도움말 파일을 만드는 데 꼭 필요한 단계는 아니지만 Doxygen의 유용한 추가 문서 기능을 보여 줍니다.

MQL5 코드셋 도움말 파일을 만드는 데 사용한 절차는 다음과 같습니다.

• MQL5 폴더 및 하위 폴더를 MQL5/files로 복사합니다.
• 제거하세요. MQL5/files/MQL5/Include/Strings/string.mqh -알 수 없는 이유로 Doxygen이 코드 구문 분석을 완료할 수 없기 때문입니다.

구조화된 주석의 추가 설명에 대한 선택 사항:

• MQL5/Files 폴더에서, 다음을 실행합니다. Windows/DOS command xcopy *.mq* c:\ /S/L > MQL5codeList.txt
• 모든 차트에서 MetaquotesCommentsToDoxygen.mq5 스크립트를 실행합니다.

결과 도움말 문서는 품질이 우수하고 유용성이 빠르게 입증됩니다. 그림 9에서 12는 확인할 수 있는 내용의 표본입니다.

그림 9. Doxygen이 생성한 클래스 목록

그림 10. CArrayObj 에 대한 Doxygen 생성 클래스 트리 다이어그램

그림 11. CArrayObj 에 대한 Doxygen 생성 멤버 함수 목록

그림 12. Doxygen이 생성한 정의 목록

3. Microsoft의 HTML 도움말 워크샵입니다.

Doxygen의 출력을 더욱 유용하게 만들려면 한 가지 단계가 더 필요합니다. Doxygen은 다른 많은 HTML 파일과 사진을 가리키는 index.html 파일을 생성합니다. 기본적으로 작은 웹사이트이기 때문에 배포하기가 매우 번거롭습니다.

오래 전에 Microsoft는 Windows 응용 프로그램용 도움말 파일이 html로 작성되어야 한다는 것을 인식하고 이를 위해 HTML 도움말 워크샵을 개발했습니다. HTML 도움말 워크샵은 Doxygen의 출력과 같은 도움말 파일 세트를 가져와 모두 단일 .chm 파일로 컴파일합니다. 이 형식은 MetaTrader 5와 함께 배포된 도움말 파일과 동일합니다.

3.1 HTML 도움말 워크숍 다운로드

Microsoft 페이지에서 htmlhelp.exe 를 다운로드하여 설치할 수 있습니다. 여기

그림 13. HTML 도움말 다운로드

3.2 컴파일된 HTML 도움말 파일 만들기

Doxygen 프로세싱의 출력은 HTML 도움말 워크샵을 통해 컴파일된 html 도움말 파일로 쉽게 변환할 수 있습니다. Doxygen은 그림 14와 같이 이 문서에서 구성한 대로 HTML 도움말 워크샵을 열 수 있는 index.hhp 파일을 생성합니다.

그림 14. Doxygen에서 생성한 index.hhp 파일의 위치

 다음 단계는 컴파일입니다:

그림 15. HTML Help 을 사용하여 컴파일링

...그리고 완료되면 그림 16 및 17과 같이 새 인덱스 .chm 파일을 MetaTrader 5/Help 폴더에 복사하고 이름을 변경할 수 있습니다.

그림 16. index.chm 위치

그림 17. index.chm이 도움말 폴더에 복사되어 이름이 변경되었습니다.

4. 요약

이 연습은 Doxygen 또는 이와 동등한 코드를 사용하여 사람들이 이해하고 사용하길 바라는 모든 MQL5 코드를 문서화할 수 있도록 도움을 줍니다. 여러분들도 그러길 바랍니다.

부록. 첨부된 Doxygen files.zip 의 파일에 대한 설명

파일	상세설명	복사
MQL5 codeset help.chm	2009년 12월 8일 MetaTrader 5 빌드 229와 함께 배포된 모든 코드가 컴파일 된 HTML 도움말 파일	MetaTrader 5/Help
MetaquotesCommentsToDoxygen.mq5	Doxygen이 주석을 해석할 수 있도록 MQL5 코드의 주석을 수정하는 스크립트	MQL5/Scripts
MQL5codeList.txt	모든 분산 MQL5 파일 목록	MQL5/Files
MQL5_Doxygen	Doxygen 구성 파일	MQL5