W przypadku projektu muszę pracować z różnymi typami plików z niektórych starych gier i pokrewnego oprogramowania - plikami konfiguracyjnymi, zapisami, archiwami zasobów i tak dalej. Większość z nich nie jest jeszcze udokumentowana, nie istnieją też narzędzia do ich obsługi, więc muszę ponownie zaprojektować formaty i zbudować własne biblioteki, aby sobie z nimi poradzić.
Chociaż nie sądzę, że istnieje duże zapotrzebowanie na większość z nich, zamierzam opublikować wyniki moich wysiłków. Czy są akceptowane standardy dokumentowania formatów plików? Rozglądając się, istnieje kilka stylów: niektóre, takie jak Specyfikacja formatu pliku .ZIP , są bardzo nieporadne; inne, jak te na XentaxWiki, są znacznie bardziej zwięzłe - niektóre z nich są trudne do odczytania; ten, który osobiście najbardziej mi się podoba, to ten opis systemu plików karty pamięci PlayStation 2 , który zawiera zarówno szczegółowy opisowy tekst, jak i kilka „map pamięci” z przesunięciami i tym podobne - również najbardziej pasuje do mojego przypadku użycia. Różnią się one nieco dla różnych formatów, ale wydaje się, że powinny istnieć pewne ogólne zasady, których powinienem przestrzegać.
Edycja: Wydaje mi się, że nie wyjaśniłem zbyt dobrze, co chcę zrobić. Pozwól mi zbudować przykład.
Mogę mieć jakieś stare oprogramowanie, które przechowuje swoją konfigurację w pliku „binarnym” - serię pól bitowych, liczb całkowitych, ciągów znaków i co nie wszystko sklejonych ze sobą i zrozumianych przez program, ale nie do odczytania przez człowieka. Rozszyfrowuję to. Chcę udokumentować dokładnie, jaki jest format tego pliku, w sposób czytelny dla człowieka, jako specyfikację implementacji biblioteki do analizowania i modyfikowania tego pliku. Ponadto chciałbym, aby inni ludzie z łatwością to zrozumieli.
Istnieje kilka sposobów napisania takiego dokumentu. Powyższy przykład PKZIP jest bardzo pracochłonny i opisuje głównie format pliku w postaci dowolnego tekstu. Przykład PS2 podaje tabele typów wartości, przesunięć i rozmiarów, wraz z obszernymi komentarzami na temat ich znaczenia. Wiele innych, takich jak te na XentaxWiki, wyświetla tylko typy i rozmiary zmiennych, z niewielkim komentarzem lub bez komentarza.
Pytam, czy istnieje jakiś standard, podobny do przewodnika stylu kodowania, który zawiera wskazówki, jak pisać tego rodzaju dokumentację. Jeśli nie, to czy istnieje jakikolwiek znany doskonały przykład, który powinienem naśladować? Jeśli nie, czy ktoś może przynajmniej streścić kilka przydatnych porad?
struct. Działa całkiem dobrze.