Difference between revisions of "Eiffeldoc"
m (s/LibertyEiffel/Liberty Eiffel/) |
Hzwakenberg (talk | contribs) m |
||
Line 220: | Line 220: | ||
==== cluster.html ==== |
==== cluster.html ==== |
||
− | Each cluster can be documented by a file <TT>cluster.html</TT>, stored in the same directory as the cluster's classes. If this file exists, Eiffeldoc extracts from it the HTML code between the elements <body> and </body>. Here too, it extracts the first sentence to use in the page that describes the whole group of clusters. |
+ | Each cluster can be documented by a file <TT>cluster.html</TT>, stored in the same directory as the cluster's classes. If this file exists, Eiffeldoc extracts from it the HTML code between the elements <body> and </body>. Here, too, it extracts the first sentence to use in the page that describes the whole group of clusters. |
---- |
---- |
Latest revision as of 13:18, 30 July 2024
eiffeldoc
is the tool that documents your Liberty Eiffel project. Currently only HTML output is supported, but maybe others will be added in the future.
Synopsis
eiffeldoc {-title title} {-home_address address} {-nav_css file} {-doc_css file} {-class_css file} {-arrow_address address} {-separator_address address} {-depends} {-prune cluster...} {-verbose} {-help} {-wiki_prefix prefix} [loadpath.se | ACE file]
-title
|
The title of the generated documentation | |
-home_address
|
The address of the go home upper-left link. If -home_address is not given, the go home upper link won't be generated.
| |
-home_image_address
|
The address of the go home image | |
-nav_css
|
The stylesheet to use in the navigation bar (i.e. the left frames) | |
-doc_css
|
The stylesheet to use in the cluster documentation (i.e. on the right frames) | |
-class_css
|
The stylesheet to use in the class documentation (i.e. on the right frames) | |
-arrow_address
|
The address of the arrow image. If the -arrow_address is not given, links in the left navigation bar won't have an arrow.
| |
-separator_address
|
The address of the separator image. If the -separator_address is not given, there will be no separation before the description of a cluster.
| |
-prune
|
Don't show the cluster nor its classes in the left navigation bar. It uses the loadpath.se or ACE syntax for paths. Note that it also removes all the subclusters. | |
-remote
|
replace the generation of that class by the address of the class generated by another instance of eiffeldoc at the given address. Note that, like -prune, the clusters don't show in eiffeldoc. It is useful for consistency. For example: eiffeldoc -remote 'lib' 'http://doc.liberty-eiffel.org/libraries/' | |
-depends
|
Generate dependant classes even if their cluster is pruned. This helps avoiding dangling links. | |
-verbose
|
Output a lot of information about what eiffeldoc is doing. | |
-wiki_prefix
|
Generate links to wiki URLs (in square brackets) |
Stylesheets
The stylesheets are heavily used to customize the output of Eiffeldoc. The known classes are:
A.home | for the home link |
A.title | for the titles |
A.cluster | for the clusters |
A.class | for the classes |
A.client | for the upper-right clients frame |
A.description | for the one-sentence description in the cluster summary |
TD.home | for the home link |
TD.title | for the titles |
TD.cluster | for the clusters |
TD.class | for the classes (except in the short proper) |
TD.client | for the upper-right clients frame |
TD.description | for the one-sentence description in the cluster summary |
B.obsolete | for the obsolete header |
I.obsolete | for the obsolete message |
TD.comment | for a class comment |
PRE.comment | for a class comment |
B.comment | for a feature clause comment |
I.comment | for a feature comment |
LI.summary | for a feature in the summary |
A.summary | for the feature link in the summary |
TD.details | for a feature definition in the details section |
B.details | for the feature name in the details section |
B.assertion | for the assertion tags |
TT.assertion | for the assertion expressions |
I.assertion | for the assertion comments |
A.link | for a class link in the class documentation |
U.wiki_entity | for a link to a field in a comment, not anchored ?Is 'anchor' the correct translation of 'lier' here? |
A.wiki_entity | for a link to a field in a comment, anchored |
B.wiki_bold | for bold elements in a comment (wiki syntax) |
I.wiki_italics | for italic elements in a comment (wiki syntax) |
TT.wiki_class_name | for class names in a comment |
TT.wiki_string | for character strings in a comment |
TT.wiki_character | for characters in a comment |
UL.wiki_bullet_list | for bullet-point lists |
LI.wiki_bullet_list | for bullet-point list items |
OL.wiki_numbered_list | for numbered lists |
LI.wiki_numbered_list | for numbered list items |
A.wiki_url | for URLs (between [...]) |
A.wiki_word | for wiki words (between [[...]]) |
Usage
Project
Eiffeldoc analyses a project's whole set of classes in order to provide HTML1 documentation organised by cluster and class. Eiffeldoc can be used to produce the API for these classes.
Eiffeldoc has been designed to generate the documentation for a whole project. But what is a project?
A project is a set of classes that makes a coherent whole: a library, an application, a set of applications, a plug-in, and so on.
Eiffeldoc defines the project by the set of class search paths. It uses the same method as finder: using the ACE file or else loadpath.se and the paths from the system configuration file.
Documentation
A high quality API does not only list its features with their signatures and contracts. The reader generally needs documentation at a higher level, which does not only explain how to call some method, but also explains the purpose of each feature and the way it is implemented, together with more general considerations.
In order to do this, Eiffeldoc uses two complementary mechanisms. The classes and their features are described by their comments; the clusters are described by a special file.
Comments
Eiffeldoc makes full use of comments. There is a convention about the position of comments.
For classes, the class comment is the comment placed just after the class declaration. For example:
class MY_CLASS -- this is the class comment end
The convention is to describe the overall purpose of the class, what it is used for, in what context, and so on.
For groups of features, the feature group comment is the comment placed just after the feature clause. For example:
feature {ANY} -- Consultation:
The convention is to use short comments, because they are used as feature group headings.
For features, the feature comment is the comment placed just after the feature signature (after the return type for attributes, after the keyword is for routines). For example:
my_routine (i: INTEGER): INTEGER is -- a function that depends on the argument `i'
The convention for complicated comments is to begin with a summary sentence. This sentence2 is extracted and used in the first part of the class description.
cluster.html
Each cluster can be documented by a file cluster.html, stored in the same directory as the cluster's classes. If this file exists, Eiffeldoc extracts from it the HTML code between the elements <body> and </body>. Here, too, it extracts the first sentence to use in the page that describes the whole group of clusters.