[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Class documentation templates (in autogsdoc)
From: |
Stefan Urbanek |
Subject: |
Re: Class documentation templates (in autogsdoc) |
Date: |
Thu, 14 Nov 2002 22:27:15 +0100 |
On 2002-11-14 18:17:44 +0100 Richard Frith-Macdonald <richard@brainstorm.co.uk>
wrote:
On Wednesday, November 13, 2002, at 08:06 pm, Stefan Urbanek wrote:
Hi,
I do not like the current layout of generated class html files. I would like to:
- add some css
- remove the author from the top - it is not necessary to have it there, better
thing wuold be to have one 'credits' file or to have all authors in the top
documentation file
- put the copyright to the bottom
- remove the 'Contents' section from class documentation
How can I specify a template for a class.html file? Or is there some other way
how I can do that?
Moreover, how can I get rid of parenthesis around protocol names in the
protocol index?
By all means add template support to the AGSHtml class (shouldn't be too hard
... I did spend some
time thinking abut how it might be done), but please leave the default layout
largely as it is,
as it's designed (meaning I thought about it) for GNUstep.
That would be great to have.
We have author information in each file, because the GNUstep libraries have
lots of authors and
they should be given credit for their individual pieces of work. I've seen
that stated as quite a
definite fsf policy, and I agree with it.
Well, I forgot to specify that I was not talking about GNUstep documentation,
but about documentation of my project.
A do not say that the autor does not have to be mentioned, but... Why user
wants to read the documentation? Usualy, because he/she wants to get
information about the library/interface/... so the software documentation
should be at first place. It is just layout issue, but I think that the author
and copyright is taking too much place at the top and still is some kind of
obstacle before user gets to the information he wants. I would like to put
authors at the bottom or as mentioned before to separate credits file in the
form like one used in books for photographs... Author Name:list of pages ... or
here as ... Author name: list of classes. Class documentation is like one page
from a book...
Users do not care about authors unles they want to give suggestion,
corrections, comments, blame...
Similar for copyright, it is better to put it at the bottom of the page, so
user will get immediately to the point. It is about readability of
documentation.
We have copyright at the top simply because that's conventional in most GNU
documentation
I've seen ... however, I don't think there is an actual gnu policy on this, so
it could be changed.
Well, as I have mentioned ... its not about conventions, but about usability.
We have a contents section in classes because the GNUstep libraries have a lot
of categories
(though it would make sense to omit it in the case where a file contains
nothing but the class
documentation).
Hm, is there a way how to specify name for group of methods as in apple's cocoa
class docs?
Stefan