This is the mail archive of the libstdc++@sourceware.cygnus.com mailing list for the libstdc++ project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

FW: Format for man pages


> please disregard if you see this message twice, problems with the mail
> server.
> 
> __soup_dragon__
> 
> "Ostinato rigore."
> Leonardo Da Vinci
> 
> -----Original Message-----
> From:	Craveiro, Marco 
> Sent:	Thursday, July 06, 2000 8:38 AM
> To:	libstdc++@sourceware.cygnus.com
> Subject:	Format for man pages
> 
> hi Everyone,
> 
> i've done some work on a format for the documentation, i was hoping this
> could be a starting point... i was already warned about the problems of
> having lots of ways of accessing a page (thanks Phil!), and any other
> ideas are most appreciated (as well as criticism, obviously).
> 
> thanks!
> 
> __soup_dragon__
> 
> "Ostinato rigore."
> Leonardo Da Vinci
> 
>  <<cppman.txt>> 
> 
title: C++ Man Pages - Some considerations on formats
author: __soup_dragon__
date: 02.07.2000

0x00: Abstract

This document tries to formalize some ideas about documenting the
standard c++ library. It is intended as a starting point only; after
the interest I saw here (the libstdc++ mailing list), I'm sure that other
developers with far better understanding of the subject will help 'us'
to achieve our 'target'. By 'us' I mean the community and by 'target'
I mean creating a sensible form of documentation. Please note that, as
far as I am concerned, everything produced will be released under the
GPL.

0x01: Background

I demostrated some interest in participating on any project to
document the new implementation of the standard c++ library (LINK). I
was then informed that no such effort exists or was planned; and after
some discussion, it appears there are some developers who find this
feature useful. 

My initial idea was (and still is) to create a set of man pages
similar to what the C library has. 

Two notes are in order before we proceed: Please note that my native
tongue is not English; and please note I got involved in this effort
because I wanted to know the library better - help me by correcting my
mistakes.

0x02: Initial ideas in terms of format

Since we are documenting OO, I think it is important to reflect it in
the documentation. A long continuous listing of all methods, enums etc.
is probably not very helpful because the information is
overwhelming. 

In fact there are different users of the information: some want an
overview of the class, others want information on a specific method
while others will want to know about it in more depth - if say, you
want to extend the functionality of a class.

I think a possible approach would be to document the class and methods
separatly. Lets see one at a time.

0x02.1: Class main man page

The proposed format is:

1. Scope. If the class is defined within another class. 

2. Inherits. List of all ancestors and type of inheritance.

2.1. Redefines. List of any features that have their export status
	  changed.

2.2. Specializes. List of any features that have their implementation
	  changed.

3. Behaviour. Short description of the behaviour of objects of this
   class (overview of the class).

4. Data members. List of all public variables, constants,
   etc. Short comments if required. Class definitons inside the class
   scope can be included here (?) but each class has its own page.

5. Messages. List of all available messages we can send, divided in
	operators, mutators, accessors. There are no details of the
	methods, just the message name and a short comment if required.

	ex:

	Mutators:

	- Replace
	- FindFirstOf
	- Insert
	(...)

The reason for choosing messages over methods in section 4 is
overloading. In my experience, most classes have several different
methods for the same message; while the function signature is vital to
make a function call, I think it is not as important when
understanding class behaviour.

Also note that we only refer to the public side of the class - nothing
private / protected is shown here. I think the man pages should focus
in interface rather than implementation. The negative point is those
who want to extend a certain class will not be able to do it through
this documentation; but it avoids having unecessary / confusing
informaition for most users.

In terms of inheritance, I think inherited features should not be
shown; For that one would have to access the partent's man page. The
Inheritance section could be somtething similar to:

Inherits: 
	A (public)
		Specializes: 
			A1, A2;
		Redifines:
			A3 as protected; 

	B (public)
		Redefines: 
			B1.
		 
In terms of displaying a main man page, one asks for it by the class name (i.e.,
man ios).
	 
As a final note, please bare in mind that the format for this section
is based in the Eiffel language made by Bertrand Meyer; In fact, I
find the short tool most useful and I see the man pages in the same
light. 

0x02.2: Class second man page

This man page is dedicated to the actual methods. It is divided in:

1. Constructors

2. Operators

3. Accessors

4. Mutators

5. Destructor

The methods should be preceeded by the message and can have comments
at both message or method level. ex:

Mutators

	Replace:

		- int Replace (int x, int y);
		  x must always be greater than zero.

		- int Replace (int x);
		(...)


Any of the items (1-5) can be used to access a second man page:

man ios::Constructors or
man ios::Mutators

It would be helpful if one could access the second man page through
any of the method names as well, i.e. ios::width().

0x03: Final Notes

IMHO, an important step forward will be given once we agree on an
outline for the pages. We can improve the class descriptions in the
future, but the boring, time-consuming job is to get everything in the
right shape.

I would appreciate feedback from anyone who reads this document - even
if only to complain how bad it is :-). Thanks for reading.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]