Trang này được dịch bởi Cloud Translation API.

Dự án ScummVM

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

Tóm tắt dự án

Tổ chức nguồn mở:: ScummVM
Người viết nội dung kỹ thuật:: b-gent
Tên dự án:: Cải thiện tài liệu mã nguồn thông qua Doxygen
Thời lượng dự án:: Thời hạn tiêu chuẩn (3 tháng)

Mô tả dự án

Tài liệu về API ScummVM (mã nguồn) hiện tại được xuất bản tại đây: https://doxygen.scummvm.org/modules.html

Tuy nhiên, API này còn thiếu nhiều khía cạnh:

1) Về cơ bản, không có cấu trúc nào, tất cả thông tin đều nổi ở cùng một cấp.

2) Các phần tử C++ được ghi nhận không nhất quán, một số phần tử không được ghi nhận. Đây là một trong những vấn đề chính mà tổ chức này đề cập.

3) Nội dung lỗi thời và không được dùng nữa vẫn xuất hiện trong dữ liệu đầu ra.

4) Ngôn ngữ và cách sử dụng thẻ doxygen phải nhất quán hơn. Bạn cần có một bộ quy tắc cho việc này, có thể là cơ sở cho hướng dẫn quy tắc lập tài liệu trong tương lai cho dự án này.

5) Bạn có thể cải thiện CSS doxygen dùng trên trang này để giống với trang web ScummVM hơn: https://www.scummvm.org

Bạn có thể giải quyết tất cả những vấn đề này trong dự án Mùa tài liệu.

Ứng dụng Season of Docs này đi kèm với một bản dự thảo PR mà tôi đã mở trong dự án để minh hoạ một số điểm cải tiến tiềm năng mà tôi đề xuất: https://github.com/scummvm/scummvm/pull/2361 Xem nội dung mô tả ở đó để biết một số thông tin chi tiết về nội dung của bản dự thảo PR và xem sự khác biệt.

Đây là khái quát về những gì liên quan đến PR:

1) Tôi nghĩ điều khó hiểu nhất hiện tại đối với những người đóng góp mới tiềm năng và nói chung là tất cả những người xem tài liệu API hiện tại là việc thiếu cấu trúc. Việc giới thiệu tài liệu API có cấu trúc sẽ cải thiện khả năng đọc, khả năng tìm kiếm và do đó, khả năng hữu dụng của bộ tài liệu. Đó là lý do tại sao PR của tôi giới thiệu các nhóm doxygen cho tất cả các tệp tiêu đề trong thư mục "common" (phổ biến). Với cấu trúc mới này, nếu muốn tìm tài liệu về API liên quan đến hệ điều hành (ví dụ:), người dùng có thể dễ dàng tìm thấy tài liệu đó trong phần điều hướng.

2) Tệp cấu hình doxygen mới được thiết lập để cho phép tạo tài liệu này.

3) Tệp "links.doxyfile", trong đó tất cả các đường liên kết được sử dụng trong bộ tài liệu đều có thể được lấy từ một nguồn. Một cơ chế hữu ích khi làm việc với doxygen.

4) CSS doxygen đã sửa đổi. Hiện tại, bài viết này được lấy từ một dự án nguồn mở khác và chỉ là điểm khởi đầu. Lý tưởng nhất là giao diện của trang doxygen phải nhất quán hơn hoặc ít hơn với trang web ScummVM.

Điều mà PR không đề cập đến nhưng chắc chắn cần được cải thiện chính là nội dung. Điều đó có nghĩa là xác định các phần mã thiết yếu chưa được ghi lại, các phần mã chưa được ghi lại đầy đủ hoặc các phần mã lỗi thời cần được xoá khỏi tài liệu. Vì chưa từng tham gia dự án này nên tôi sẽ cần được sự hướng dẫn của cố vấn để đạt được mục tiêu này.

Tất nhiên, việc chúng tôi có triển khai bất kỳ nội dung nào trong thông cáo báo chí hay không còn tuỳ thuộc vào cuộc thảo luận với tổ chức. Tôi nghĩ rằng hành động quan trọng hơn lời nói. Vì vậy, tôi quyết định thể hiện việc mình có thể làm thay vì chỉ mô tả trong đơn đăng ký.

Tổ chức đã cung cấp tiến trình dự kiến sau đây cho dự án này: Tuần Nhiệm vụ chính Tuần 0 (Trước ngày 9/14) Thảo luận và xem xét đề xuất Tuần 1 (9/14) Thiết lập bản dựng Doxygen Tuần 2 (9/21) Làm mới giao diện Doxygen (ưu tiên thấp) Tuần 3 (9/28) Mã chung – OSystem, FS, Cấu trúc dữ liệu, Chuỗi, v.v. Tuần 4 (10/05) Mã chung – Tiếp tục Tuần 5 (10/12) Công cụ – Mã chung và công cụ mẫu Tuần 6 (10/19) Đồ hoạ Tuần 7 (10/26) Âm thanh Tuần 8 (11/02) Video, Hình ảnh Tuần 9 (11/09) Phần phụ trợ – Nền tảng, Đồ hoạ, Sự kiện Tuần 10 (11/23) Phần phụ trợ – Tiếp tục Tuần 11 (11/30) Tóm tắt và gửi dự án

Thay đổi duy nhất tôi muốn đề xuất là bắt đầu bằng cách xây dựng cấu trúc, như đã đề cập. Điều này có thể được thực hiện trong tuần 1 và 2, cùng với việc thiết lập bản dựng doxygen (phần lớn đã được thực hiện) và làm mới da Doxygen. Sau đó, tôi đồng ý rằng điều hợp lý nhất là đi qua từng phần với người cố vấn để xác định vấn đề và cải thiện tài liệu doxygen.

Tôi thấy đây là một dự án có độ dài tiêu chuẩn nhưng tôi chắc chắn rằng có những cải tiến khác liên quan đến tài liệu API có thể được thực hiện sau khi dự án GSoD hoàn tất. Ví dụ: nghĩ ra hướng dẫn định kiểu cho tài liệu và thêm vào wiki để người đóng góp biết cách họ nên ghi chép đoạn mã họ sẽ thêm.

Tôi rất sẵn lòng giúp bạn thực hiện những việc như thế này sau khi sự cố GSoD kết thúc. Tôi chắc chắn rằng ScummVM có thể sử dụng một người viết kỹ thuật để đảm bảo tài liệu API của họ có chất lượng tốt và dễ sử dụng. Tôi cũng có thể thấy rằng mình có nhiều dự án tài liệu khác trong tương lai có thể hỗ trợ bạn, chẳng hạn như tạo hướng dẫn về cách làm việc với trình bổ trợ.