MATLAB m-file giúp định dạng

Question

Tôi không thể tìm thấy định dạng nào có sẵn để viết trợ giúp cho hàm MATLAB của riêng bạn. Rất ít thông tin có sẵn in official documentation.

Bạn có biết về bất kỳ định dạng nào khác có thể hiển thị với Trình duyệt trợ giúp (không có chức năng trợ giúp) không? Vì nó dành cho các chức năng tích hợp sẵn. Cách định dạng tiêu đề (như Cú pháp, Mô tả, Ví dụ)? Là viên đạn, bàn có thể? Hoặc có thể là một tệp riêng biệt?

Tôi đã thử đánh dấu văn bản như được sử dụng cho PUBLISH và HTML, không hoạt động.

Tôi chỉ tìm thấy một điều thú vị. Nếu chức năng của bạn chứa trường hợp hỗn hợp, như testHelpFunction, tên của nó sẽ được đánh dấu:

Không làm nổi bật nếu nó chỉ là testhelpfunction.

Bất kỳ suy nghĩ nào khác?

CẬP NHẬT

Đây là tài liệu phong phú tôi tìm thấy trên tạo ra các file của bạn riêng giúp đỡ:

Providing Your Own Help and Demos
(Chết liên kết thay thế bằng liên kết lưu trữ web)

---

(Chết liên kết đã xóa)

---

cập nhật một lần nữa:

• Add Help for Your Program
• Display Custom Documentation

Answer 1

Hãy thử phần khác trong tài liệu chính thức. Đó là kỹ lưỡng hơn. MATLAB> Hướng dẫn sử dụng> Công cụ máy tính để bàn và Môi trường phát triển> Tùy chỉnh trợ giúp và trình diễn> Cung cấp trợ giúp và bản trình diễn của riêng bạn. Điều này mô tả cả helptext đơn giản và tạo các tệp trợ giúp HTML riêng biệt.

Đây là định dạng văn bản trợ giúp tôi đã chọn và thấy hữu ích.

function foo(x,y,z) 
%FOO One-line description goes here 
% 
% foo(x,y,z) 
% 
% Multi-line paragraphs of descriptive text go here. It's fine for them to 
% span lines. It's treated as preformatted text; help() and doc() will not 
% re-wrap lines. In the editor, you can highlight paragraphs, right-click, 
% and choose "Wrap selected comments" to re-flow the text. 
% 
% More detailed help is in the <a href="matlab: help foo>extended_help">extended help</a>. 
% It's broken out like this so you can keep the main "help foo" text on 
% a single screen, and then break out obscure parts to separate sections. 
% 
% Examples: 
% foo(1,2,3) 
% 
% See also: 
% BAR 
% SOMECLASS/SOMEMETHOD 

disp(x+y+z); 

function extended_help 
%EXTENDED_HELP Some additional technical details and examples 
% 
% Here is where you would put additional examples, technical discussions, 
% documentation on obscure features and options, and so on. 

error('This is a placeholder function just for helptext'); 

• Dòng đầu tiên sau khi chữ ký chức năng được gọi là "dòng H1". Nó cần phải chỉ là một dòng để nó được lấy đúng bởi contentrpt(), có thể tự tạo một tệp Contents.m từ văn bản trợ giúp trong các hàm của bạn
• Tên hàm trong dòng H1 là tất cả mũ, bất kể viết hoa thực tế của tên hàm trong chữ ký
• Trường hợp quan trọng đối với "Xem thêm". Tôi không chắc tất cả các trường hợp đều hoạt động; cái này chắc chắn.
• Tên chức năng sau "Xem thêm:" là tất cả các mũ. Tên phương thức có đủ điều kiện; Tôi nghĩ rằng tên của các phương thức trong cùng một lớp như phương pháp hiện tại có thể không đủ điều kiện.

Mọi thứ giữa dòng H1 và "Ví dụ:" chỉ là định dạng thông thường mà tôi thấy có thể đọc được; help() không xử lý nó một cách đặc biệt.

Bạn có thể sử dụng một dạng siêu liên kết giới hạn để được trợ giúp. Đặc biệt, bạn có thể sử dụng các siêu liên kết để gọi các lệnh Matlab tùy ý và trỏ đến các phần khác của helptext bằng cách yêu cầu nó trợ giúp(). Bạn có thể sử dụng nó để trỏ đến bất kỳ hàm nào; "function> subfunction" chỉ là cú pháp để giải quyết các hàm con trong các lời gọi help(). Thật không may, vì bạn cần phải đặt "trợ giúp" hoặc "doc" trong các siêu kết nối đó, nó chỉ hoạt động trong một hoặc biểu mẫu trình bày khác. Sẽ đẹp hơn nếu có dạng siêu liên kết trợ giúp trực tiếp.

Answer 2

Tôi hình dung có một số (xem ví dụ), nhưng tôi đã không bao giờ tìm thấy các tài liệu thích hợp. Tôi thường có khối như:

% ... 
% 
% See also: 
% this_other_function() 
% 
% <author> 

Và phần See also được định dạng như một tiêu đề, nhưng nếu bạn thay thế See also bởi cái gì khác, nó không hoạt động. Nếu bất kỳ ai tìm thấy danh sách các tựa đề được hỗ trợ như vậy, vui lòng liên kết với nó ở đây!

EDIT:

Tôi vừa mới đến để tìm hiểu về hệ thống xuất bản built-in matlab của. Có vẻ như các bình luận MATLAB hỗ trợ một số hình thức đánh dấu không xa so với cú pháp Markdown (như được sử dụng trên bản thân SO), với sự hỗ trợ cho các phương trình LaTeX và tất cả.

Có một bài đăng của "Loren trên nghệ thuật MATLAB" với số short introduction về xuất bản và đánh dấu. Để tham khảo đầy đủ, hãy xem Making Up MATLAB Comments for Publishing trên trang web Mathworks.

Khi mã của bạn đã sẵn sàng, bạn có thể xuất kết quả sang HTML/PDF/XML, v.v. bằng cách sử dụng publish() function.Tôi sử dụng đoạn mã sau để xuất các tệp của mình:

% Other formats are supported, refer to documentation. 
options.format = 'html'; 

    % I don't evaluate the code, especially for functions that require arguments. 
    % However, if providing a demo, turning this on is a fantastic way to embed 
    % figures in the resulting document. 
options.evalCode = false; 

    % You can run this in a loop over files in the currrent directory if desired. 
publish('script.m', options); 

Answer 3

Tôi nghĩ khía cạnh quan trọng nhất trong định dạng trợ giúp là có sự trợ giúp và định dạng của bạn nhất quán để bạn (và những người làm việc với bạn) không lãng phí thời gian tìm cách tìm kiếm thông tin. Lưu ý rằng đối với OOP, rất hữu ích khi có một lớp cha với phương thức 'help' gọi là doc(class(obj)), vì bạn không thể dễ dàng truy cập trợ giúp từ việc khởi tạo lớp học của bạn

Để giúp tôi nhất quán (và để đảm bảo Tôi không quên công cụ), tôi đã tạo một automatic function template trên trao đổi tệp.

Đây là tiêu đề tối thiểu

function testhelp 
%TESTHELP is an example (this is the H1 line) 
% 
% SYNOPSIS: a=testhelp(b,c) 
% 
% INPUT b: some input parameter 
%  c: (opt) some optional input parameter. Default: [] 
% 
% OUTPUT a: some output parameter 
% 
% REMARKS This is just an example, it won't run 
% 
% SEE ALSO testHelpFunction 
% 
% created with MATLAB ver.: 7.11.0.584 (R2010b) on Mac OS X Version: 10.6.4 Build: 10F569 
% 
% created by: Jonas 
% DATE: 01-Oct-2010 
%