[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: autogsdoc change
From: |
Richard Frith-Macdonald |
Subject: |
Re: autogsdoc change |
Date: |
Tue, 6 Dec 2011 14:37:55 +0000 |
On 6 Dec 2011, at 12:52, Daniel Santos wrote:
> I would like to do some more. Since I am still getting to know the tool I
> noticed that no cross references are generated among types (NSError refers
> NSString but does not link to it.),
That's odd ... you should certainly be seeing cross references. For instance
if you look at the documentation of NSError at
http://www.gnustep.org/resources/documentation/Developer/Base/Reference/index.html
you will see cross references to NSString. But that's a cross reference
between classes ... I don't think there's any easy markup for referring to
structures, bitfields, and other plain C types.
> and no table of contents was generated. Is this always the case, or have I
> missed any option ?
I guess you've missed an option ... there's markup to generate indexes (the
'index' element) which you can put in a template document
(see
http://www.gnustep.org/resources/documentation/Developer/Tools/Reference/gsdoc.html).
There's also standardised stuff to put things in frames for easy navigation
(with a table of contents).
> If I were to add these two features, can I just do it and then submit the
> code to the list ?
Well, I think we already have those ... but maybe they don't work for you or
are hard to figure out or find ... fixing/improving that might be good.
Anything which makes it simpler/easier to do things is good.
> How do one suggest changes, and how do they get approved ?
The mailing list is a good place to find out if anyone objects to anything, and
as I'm the maintainer for base, it's my job to make the decision ... but my
basic principle is that if someone wants to work to improve something, I'm in
favour of whatever makes them happy.
The project does have certain rules of course ... for anything other than very
short fixes we need copyright assignment so that the code will be owned by the
Free Software Foundation (they lease it back to you so you can do what you like
with it, but they hold the copyright so they can legally chase anyone else who
tries to incorporate it into proprietory software) ... so of course you must
have written any contribution yourself.
Any code must conform to the coding standards and match the style of the
existing code, and must of course work without breaking the existing code.
Beyond that, the aim is generally to improve the existing codebase ... make it
simpler, more maintainable, easier to use, more clearly documented, better
tested etc. Adding new features is less obviously good ... if something new
means the code is more complex, less maintainable, and harder to use then it
had better be really useful (or necessary for OSX compatibility).
> If the development team doesn't think it has any value, one needs to know
> before making the effort.
Well, if *you* think something is valuable, I would accept it even if I didn't
... as long as it didn't look harmful (making things too complex or breaking
existing code). The more people who are interested in doing things, the better.
There certainly *are* things that need work in autogsdoc (a new version of the
markup language to support the new objective-c 2.0 features, and corresponding
support in the code for instance).
> PS : I would also try to modularize the code a bit more. (more methods,
> shorter)
Yes (though not too short) ... I'm not proud of the autogsdoc code ... never
had time to polish it ... I'm sure there's cleanup/consistency/restructuring
that could be usefully done.