autogsdoc - Generator dokumentacji API GNUstep i konwerter XML->HTML
autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO] [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-DocumentationDirectory path] [-Declared location] [-Project title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate filename] [-VariablesTemplate filename] [-SystemProjects string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
Narzędzie autogsdoc to narzędzie wiersza poleceń, które pomaga programistom w tworzeniu dokumentacji referencyjnej dla interfejsów API GNUstep. Umożliwia także programistom pisanie i utrzymywanie innej dokumentacji w formacie XML oraz konwertowanie jej do formatu HTML. Szczegółowo autogsdoc:
Wyodrębnij specjalne komentarze opisujące publiczne interfejsy klas, kategorii, protokołów, funkcji i makr z kodu źródłowego Objective C (pliki nagłówkowe i opcjonalnie pliki źródłowe) do plików GSDoc XML.
Konwertuj pliki XML GSDoc, niezależnie od tego, czy zostały wygenerowane z kodu źródłowego, czy napisane ręcznie przez programistów, do formatu HTML.
Twórz indeksy w oparciu o zestawy plików GSDoc XML i konwertuj je również do formatu HTML.
Najczęstszym zastosowaniem jest uruchomienie polecenia z jedną lub kilkoma nazwami plików nagłówkowych jako argumentami ... narzędzie automatycznie przeanalizuje odpowiednie pliki źródłowe w tym samym katalogu co nagłówki (lub bieżący katalog lub katalog określony za pomocą DocumentationDirectory default) i tworzy pliki GSDoc i HTML jako dane wyjściowe. Aby uzyskać najlepsze wyniki, tryb ten należy uruchomić z katalogu zawierającego pliki źródłowe. (Zauważ, że ponieważ C jest podzbiorem Celu C, to narzędzie może działać w celu dokumentowania funkcji i innych struktur C w zwykłym źródle C.)
Pliki GSDoc mogą być również podane bezpośrednio jako dodatek lub same i zostaną przekonwertowane na format HTML. Zobacz dokumentację GSDoc HTML lub stronę podręcznika gsdoc(7), aby uzyskać informacje na temat formatu GSDoc.
Wreszcie, pliki HTML mogą być podawane w wierszu poleceń. Znajdujące się w nich odsyłacze do innych części dokumentacji kodu zostaną przepisane na podstawie tego, co znajduje się obecnie w projekcie.
Parser kodu źródłowego automatycznie utworzy dokumenty GSDoc z listą metod w klasach znalezionych w plikach źródłowych i będzie zawierał tekst ze specjalnie sformatowanych komentarzy z plików źródłowych.
Każdy komentarz rozpoczynający się od ukośnika i dwóch gwiazdek, a nie od zwykłego ukośnika i pojedynczej gwiazdki, jest traktowany jako znacznik GSDoc, używany jako opis następującej po nim klasy lub metody. Ten tekst komentarza jest ponownie formatowany, a następnie wstawiany do danych wyjściowych.
Jeśli wiele komentarzy jest powiązanych z tym samym elementem, są one w razie potrzeby łączone ze sobą za pomocą podziału wiersza (
).Narzędzie może być łatwo wykorzystane do dokumentowania programów, jak i bibliotek, po prostu przez nadanie mu nazwy pliku źródłowego zawierającego funkcję main() programu - pobiera specjalne komentarze z tej funkcji i specjalnie je obsługuje, wstawiając je jako sekcja na końcu pierwszego rozdziału dokumentu (w razie potrzeby tworzy pierwszy rozdział).
Opcje zostały opisane w sekcji Argumenty i ustawienia domyślne poniżej.
W niektórych przypadkach wykonywane jest specjalne dodatkowe przetwarzanie, głównie w pierwszym komentarzu znalezionym w pliku źródłowym, z którego można wyodrębnić różne fragmenty znaczników GSDoc i umieścić je w odpowiednich miejscach w dokumencie wyjściowym -
W każdym wierszu, w którym znajduje się AutogsdocSource:, pozostała część wiersza jest traktowana jako nazwa pliku źródłowego do użycia, zamiast zakładać, że każdy przetwarzany plik .h używa pliku .m tego samego nazwa. Możesz podać wiele wierszy AutogsdocSource:, w których plik nagłówkowy deklaruje elementy zdefiniowane w wielu plikach źródłowych. Jeśli nazwa pliku jest bezwzględna, jest używana tak, jak podano. Z drugiej strony, jeśli jest to ścieżka względna, oprogramowanie szuka pliku źródłowego najpierw względem lokalizacji pliku nagłówkowego, a jeśli go tam nie znajdzie, względem bieżącego katalogu, w którym działa autogsdoc, a na końcu względem katalog określony przez domyślny DocumentationDirectory.
Abstrakt treści dokumentu... umieszczony w nagłówku wyjścia GSDoc.
Opis autora kodu - może być powtarzany w przypadku, gdy dokument ma wielu autorów. Umieszczony w nagłówku wyjścia GSDoc. W celu ułatwienia czytelności źródła przeprowadzane jest specjalne dodatkowe przetwarzanie związane z autorem dokumentu - Dowolna linia formularza
nazwa
nazwa
imię” lub
name” zostanie rozpoznany i przekonwertowany na element author, prawdopodobnie zawierający element email.
Umieszczony w wyjściu GSDoc tuż przed końcem treści dokumentu - przeznaczony do wykorzystania w załącznikach, indeksie itp.
Umieszczony bezpośrednio przed jakąkolwiek wygenerowaną dokumentacją klasy ... przeznaczony do użycia w celu zapewnienia ogólnego opisu działania dokumentowanego kodu. Wszelka dokumentacja funkcji main() programu jest dodawana jako sekcja na końcu tego rozdziału.
Prawa autorskie do treści dokumentu ... umieszczone w nagłówku wyjścia GSDoc. Aby ułatwić czytelność źródła, przeprowadzane jest specjalne dodatkowe przetwarzanie — Dowolna linia w formacie „Tekst chroniony prawem autorskim (C)” zostanie rozpoznana i przekonwertowana na element kopiuj.
Data rewizji dokumentu ... umieszczona w nagłówku wyjścia GSDoc. Jeśli zostanie to pominięte, narzędzie spróbuje skonstruować wartość ze znacznika daty RCS (jeśli jest dostępny).
Wstawiony do dokumentu na początku treści ... przeznaczony do wprowadzenia lub spisu treści itp.
Tytuł dokumentu ... umieszczony w nagłówku wyjścia GSDoc. Jeśli zostanie to pominięte, narzędzie wygeneruje własny (prawdopodobnie kiepski) tytuł - dlatego należy ręcznie dołączyć ten znacznik.
Identyfikator wersji dokumentu ... umieszczony w nagłówku wyjścia GSDoc. Jeśli zostanie to pominięte, narzędzie spróbuje skonstruować wartość ze znacznika RCS Revision (jeśli jest dostępny).
NB Opisane znaczniki mogą być używane w dokumentacji klas, kategorii lub protokołów ... jeśli tak, są wyodrębniane i owijane wokół reszty dokumentacji klasy jako rozdział klasy. Reszta dokumentacji klasy jest zwykle wstawiana na końcu rozdziału, ale zamiast tego można ją zastąpić pseudoelementem
W komentarzach używanych do dostarczania tekstu do opisu metody następujące znaczniki są usuwane z tekstu i traktowane w specjalny sposób -
Metoda jest oznaczona jako wyznaczony inicjator dla klasy.
Metoda jest oznaczona jako taka, którą podklasy muszą nadpisać (np. metoda abstrakcyjna).
Metoda jest oznaczona jako taka, której podklasy NIE powinny zastępować.
Znacznik jest usuwany z opisu i umieszczany po na wyjściu GSDoc - tak, że metoda jest opisana jako zgodna (lub niezgodna) z określonymi standardami.
Ogólnie rzecz biorąc, tekst w komentarzach jest ponownie formatowany w celu ujednolicenia i ładnego wcięcia ... ponowne formatowanie nie jest wykonywane na żadnym tekście wewnątrz elementu
Pewne dobrze znane stałe, takie jak YES, NO i nil, są zawarte w znacznikach ... .
Nazwy argumentów metod w opisach metod są zawarte w znacznikach ... .
Nazwy metod (zaczynające się od plusa lub minusa) są ujęte w znaczniki
Specyfikatory metod zawierające nazwy klas (rozpoczynające się i kończące nawiasami kwadratowymi) są zawarte w znacznikach
Nazwy funkcji (kończące się na '()') inne niż 'main()' są ujęte w znacznikach
Narzędzie akceptuje pewne ustawienia domyślne użytkownika (które oczywiście można podać jako argumenty wiersza poleceń, dodając „-” przed nazwą domyślną i podając wartość później, jak w -Clean YES):
Jeśli ta wartość logiczna jest ustawiona na TAK, to zamiast generować dokumentację, narzędzie usuwa wszystkie pliki GSDoc wygenerowane w projekcie i wszystkie wygenerowane z nich pliki html (jak również te, które zostałyby wygenerowane z jawnie wymienionych plików GSDoc) i ostatecznie usuwa plik indeksu projektu. Jedynym wyjątkiem jest to, że pliki szablonów GSDoc (tj. te określone przy użyciu argumentów "-ConstantsTemplate...", "-FunctionsTemplate..." itp.) nie są usuwane, chyba że ustawiona jest flaga CleanTemplates.
Ta flaga określa, czy pliki szablonów GSDoc mają być usuwane wraz z innymi plikami, gdy określona jest opcja Wyczyść. Domyślnie nie są one usuwane ... ponieważ te szablony mogły zostać utworzone ręcznie i po prostu wstawiono do nich dane.
Określ nazwę dokumentu szablonu, do którego ma zostać wstawiona dokumentacja o stałych ze wszystkich plików w projekcie. Jest to przydatne, jeśli stałe w kodzie źródłowym są rozproszone po wielu plikach i trzeba je zgrupować w jednym miejscu. Jesteś odpowiedzialny za upewnienie się, że podstawowy dokument szablonu (do którego wstawiana jest indywidualna stała dokumentacja) zawiera wszystkie inne potrzebne informacje, ale dla wygody autogsdoc wygeneruje dla ciebie prosty szablon (który możesz następnie edytować), jeśli plik nie nie istnieje. Wstawienie odbywa się bezpośrednio przed elementem back (lub jeśli go nie ma, bezpośrednio przed końcem elementu body) w szablonie.
Określ, gdzie nagłówki mają być udokumentowane jako znalezione. Rzeczywista nazwa tworzona w dokumentacji jest tworzona przez dodanie ostatniego składnika nazwy pliku nagłówkowego do wartości this default. Jeśli ta wartość domyślna nie jest określona, używana jest pełna nazwa pliku nagłówkowego (podana w wierszu polecenia) z domyślnym rozszerzeniem HeaderDirectory na początku. Typowym zastosowaniem tego może być „„-Declared Foundation”” podczas generowania dokumentacji dla podstawowej biblioteki GNUstep. Spowodowałoby to, że dokumentacja mówi, że NSString jest zadeklarowany w „Foundation/NSString.h”
Ta flaga umożliwia generowanie dokumentacji dla wszystkich zmiennych instancji. Zwykle dokumentowane będą tylko te, które zostały wyraźnie określone jako „publiczne” lub „chronione”.
Ta flaga pozwala na całkowite wyłączenie dokumentacji dla zmiennych instancji. Zwykle udokumentowane zostaną jawnie zadeklarowane „publiczne” lub „chronione” zmienne instancji.
Ta flaga, jeśli jest ustawiona, nakazuje generatorowi HTML umieszczenie dokumentacji zmiennej instancji na końcu klasy, zamiast na początku. Jest to przydatne, jeśli używasz wielu chronionych zmiennych instancji, które będą miały drugorzędne znaczenie dla zwykłych użytkowników klasy.
Może służyć do określenia katalogu, w którym ma zostać umieszczona wygenerowana dokumentacja. Jeśli to nie jest ustawione, dane wyjściowe są umieszczane w bieżącym katalogu. Ten katalog jest również używany w ostateczności do lokalizowania plików źródłowych (nie nagłówków), a co ważniejsze, jest używany jako pierwszy i jedyny sposób lokalizowania wszelkich plików .gsdoc przekazywanych w wiersz poleceń. Wszelkie informacje o ścieżce podane dla tych plików są usuwane i są wyszukiwane w „DocumentationDirectory” (nawet jeśli nie zostały wygenerowane automatycznie).
Określa nazwę pliku zawierającego listę nazw plików w formacie tablicy właściwości (nazwa1,nazwa2,...). Jeśli to jest obecne, nazwy plików na liście argumentów programu są ignorowane, a nazwy w tym pliku są używane jako lista nazw do przetworzenia.
Określ nazwę dokumentu szablonu, do którego ma zostać wstawiona dokumentacja funkcji ze wszystkich plików w projekcie. Jest to przydatne, jeśli kod źródłowy funkcji jest rozproszony po wielu plikach i trzeba go zgrupować w jednym miejscu. Jesteś odpowiedzialny za upewnienie się, że podstawowy dokument szablonu (do którego wstawiana jest dokumentacja poszczególnych funkcji) zawiera wszystkie inne potrzebne informacje, ale dla wygody autogsdoc wygeneruje dla ciebie prosty szablon (który możesz następnie edytować), jeśli plik nie nie istnieje. Wstawienie odbywa się bezpośrednio przed elementem back (lub jeśli go nie ma, bezpośrednio przed końcem elementu body) w szablonie.
Może służyć do określenia, czy mają być generowane dane wyjściowe HTML. Domyślnie TAK.
Może służyć do określenia katalogu, w którym mają być przeszukiwane pliki nagłówkowe. Po podaniu ta wartość jest dołączana do względnych nazw nagłówków, w przeciwnym razie względne nazwy nagłówków są interpretowane względem bieżącego katalogu. To ustawienie domyślne nie ma wpływu na pliki nagłówkowe określone jako ścieżki bezwzględne.
Wartość logiczna, której można użyć do określenia, że program powinien ignorować czasy modyfikacji plików i mimo to regenerować pliki. Dostarczony do użytku w połączeniu z systemem „make”, który ma samodzielnie zarządzać sprawdzaniem zależności.
Ta wartość służy do sterowania automatycznym włączaniem lokalnych projektów zewnętrznych do systemu indeksowania w celu generowania odsyłaczy w końcowym dokumencie wyjściowym. Jeśli ustawione na 'Brak', to żadne lokalne odwołania do projektów nie są wykonywane, w przeciwnym razie 'Lokalny' katalog dokumentacji GNUstep jest rekurencyjnie przeszukiwany w poszukiwaniu plików z rozszerzeniem '.igsdoc' i używane są informacje indeksowania z tych plików. Wartość tego ciągu jest również używana do generowania nazw plików w odsyłaczach ... jeśli jest to pusty ciąg, zakłada się, że ścieżka do użycia jest plikiem w tym samym katalogu, w którym znaleziono plik igsdoc, w przeciwnym razie jest to używany jako przedrostek nazwy w indeksie. Uwaga. Lokalne projekty o takiej samej nazwie jak obecnie dokumentowany projekt nie zostaną uwzględnione w tym mechanizmie. Jeśli chcesz dołączyć takie projekty, musisz to zrobić jawnie, używając -Projects ...
Określ nazwę dokumentu szablonu, do którego ma zostać wstawiona dokumentacja dotycząca makr ze wszystkich plików w projekcie. Jest to przydatne, jeśli kod makra jest rozproszony w wielu plikach i trzeba go zgrupować w jednym miejscu. Jesteś odpowiedzialny za upewnienie się, że podstawowy dokument szablonu (do którego wstawiana jest indywidualna dokumentacja makr) zawiera wszystkie inne potrzebne informacje, ale dla wygody autogsdoc wygeneruje dla ciebie prosty szablon (który możesz następnie edytować), jeśli plik nie nie istnieje. Wstawienie odbywa się bezpośrednio przed elementem back (lub jeśli go nie ma, bezpośrednio przed końcem elementu body) w szablonie.
Nazwa pliku, która ma być używana do wyprowadzania informacji o zależnościach dla make. Przyjmie to formę listy wszystkich plików nagłówkowych i źródłowych znanych dla projektu jako zależności nazwy projektu (patrz „Projekt”).
Może być używany do określenia nazwy tego projektu ... określa nazwę pliku referencyjnego indeksu utworzonego jako część dokumentacji w celu dostarczenia informacji umożliwiających innym projektom odsyłacze do pozycji w tym projekcie.
Ta wartość może być dostarczona jako słownik zawierający ścieżki do indeksu/plików referencyjnych igsdoc używanych przez projekty zewnętrzne, wraz z wartościami używanymi do mapowania nazw plików znalezionych w indeksach. Na przykład, jeśli plik indeksu projektu (igsdoc) mówi, że klasa „Foo” znajduje się w pliku „Foo”, a ścieżka powiązana z tym indeksem projektu to „/usr/share/doc/proj”, to wygenerowany html wyjście może odwoływać się do klasy jako znajdującej się w '/usr/share/doc/prj/Foo.html' . Zauważ, że słownik można podać w wierszu poleceń, używając standardowego formatu PropertyList (nie formatu XML OS X), używając średników jako separatorów wierszy i umieszczając go w pojedynczych cudzysłowach.
Wartość logiczna, której można użyć do określenia, że program powinien rejestrować, które pliki są regenerowane z powodu ich zależności od innych plików.
Wartość logiczna używana do określenia, czy program powinien wstawiać do dokumentacji informacje o zgodności ze standardami. Powinno to być używane tylko podczas dokumentowania samych bibliotek i narzędzi GNUstep, ponieważ zakłada, że dokumentowany kod jest częścią GNUstep i prawdopodobnie jest zgodny ze standardem OpenStep lub implementuje metody kompatybilne z MacOS-X.
Ta wartość służy do sterowania automatycznym włączaniem zewnętrznych projektów systemowych do systemu indeksowania w celu generowania odsyłaczy w ostatecznym wydaniu dokumentu. Jeśli ustawione na 'Brak', to żadne odwołania do projektów systemowych nie są wykonywane, w przeciwnym razie katalog dokumentacji GNUstep 'System' jest rekurencyjnie przeszukiwany w poszukiwaniu plików z rozszerzeniem '.igsdoc' i używane są informacje indeksujące z tych plików. Wartość tego ciągu jest również używana do generowania nazw plików w odsyłaczach ... jeśli jest to pusty ciąg, zakłada się, że ścieżka do użycia jest plikiem w tym samym katalogu, w którym znaleziono plik igsdoc, w przeciwnym razie jest to używany jako przedrostek nazwy w indeksie. Uwaga. Projekty systemowe o takiej samej nazwie jak obecnie dokumentowany projekt nie zostaną uwzględnione w tym mechanizmie. Jeśli chcesz dołączyć takie projekty, musisz to zrobić jawnie, używając -Projects ...
Określ nazwę dokumentu szablonu, do którego ma zostać wstawiona dokumentacja dotycząca definicji typów ze wszystkich plików w projekcie. Jest to przydatne, jeśli kod źródłowy typedef jest rozproszony w wielu plikach i trzeba go zgrupować w jednym miejscu. Jesteś odpowiedzialny za upewnienie się, że podstawowy dokument szablonu (do którego wstawiana jest indywidualna dokumentacja typedef) zawiera wszystkie inne potrzebne informacje, ale dla wygody autogsdoc wygeneruje dla ciebie prosty szablon (który możesz następnie edytować), jeśli plik nie nie istnieje. Wstawienie odbywa się bezpośrednio przed elementem back (lub jeśli go nie ma, bezpośrednio przed końcem elementu body) w szablonie.
Łańcuch używany do podania nazwy, która ma być użyta w łączu „w górę” z wygenerowanych dokumentów GSDoc. Zwykle powinna to być nazwa pliku zawierającego indeks zawartości projektu. Jeśli tego brakuje lub jest ustawiony na pusty ciąg, w dokumentach nie zostanie podany link „w górę”.
Określ nazwę szablonu dokumentu, do którego ma zostać wstawiona dokumentacja o zmiennych ze wszystkich plików w projekcie. Jest to przydatne, jeśli zmienny kod źródłowy jest rozproszony w wielu plikach i trzeba go zgrupować w jednym miejscu. Jesteś odpowiedzialny za upewnienie się, że podstawowy dokument szablonu (do którego wstawiana jest dokumentacja poszczególnych zmiennych) zawiera wszystkie inne potrzebne informacje, ale dla wygody autogsdoc wygeneruje dla ciebie prosty szablon (który możesz następnie edytować), jeśli plik nie nie istnieje. Wstawienie odbywa się bezpośrednio przed elementem back (lub jeśli go nie ma, bezpośrednio przed końcem elementu body) w szablonie.
Wartość logiczna używana do określania, czy mają być generowane szczegółowe dane wyjściowe debugowania/ostrzeżenia.
Wartość logiczna używana do określenia, czy chcesz wygenerować standardowe wyjście ostrzegawcze (np. raport o nieudokumentowanych metodach).
Ta wartość jest słownikiem używanym do mapowania identyfikatorów/słów kluczowych znalezionych w plikach źródłowych na inne słowa. Zasadniczo nie będziesz musiał tego używać, ale czasami pomocne jest uniknięcie dezorientacji parsera przez użycie makr preprocesora C. Możesz skutecznie przedefiniować makro na coś mniej mylącego. Wartość, na którą mapujesz identyfikator, musi być jedną z następujących wartości: inny identyfikator, pusty ciąg — wartość jest ignorowana, dwa ukośniki („//”) — reszta wiersza jest ignorowana. Zauważ, że słownik można podać w wierszu poleceń, używając standardowego formatu PropertyList (nie formatu XML OS X), używając średników jako separatorów wierszy i umieszczając go w pojedynczych cudzysłowach.
Wartość domyślna „Do góry” jest używana do określenia nazwy dokumentu, który powinien być używany jako łącze „w górę” dla innych używanych dokumentów. Ta nazwa nie może zawierać ścieżki ani rozszerzenia. Ogólnie rzecz biorąc, dokument, do którego odnosi się to domyślnie, powinien być ręcznie edytowanym dokumentem GSDoc, który powinien mieć sekcję wstecz zawierającą indeks projektu. np.
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">
<head>
<title>My project reference</title>
<author name="my name"></author>
</head>
<body>
<chapter>
<heading>My project reference</heading>
</chapter>
<back>
<index scope="project" type="title" />
</back>
</body>
</gsdoc> Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .htmlKilka elementów GSDoc nie jest jeszcze poprawnie renderowanych w HTML. Są to:
Komunikaty o błędach i ostrzeżenia mogą pochodzić z każdego etapu potoku: kontroli najwyższego poziomu, analizowania źródła, analizowania GSDoc i indeksowania.
gsdoc(7), GNUstep(7)
Autogsdoc połączył możliwości dwóch wcześniejszych narzędzi, 'autodoc' i 'gsdoc', które wykonywały odpowiednio tłumaczenia source->GSDoc i GSDoc->HTML. Te wcześniejsze narzędzia i format GSDoc zostały opracowane dla GNUstep w oparciu o wcześniejszy język GDML SGML.
Ta strona podręcznika pojawiła się po raz pierwszy w gnustep-base 1.9.2 (marzec 2004).
autogsdoc został napisany przez Richarda Frith-Macdonalda
Ta strona podręcznika została dodana przez Adriana Roberta