gnustep-dev
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: autogsdoc change


From: Daniel Santos
Subject: Re: autogsdoc change
Date: Tue, 6 Dec 2011 17:14:52 +0000

Ok. Maybe I am not using it the right way. I am executing the following command :

autogsdoc -DocumentationDirectory ~/doc/GNUstep/base gnustep/modules/core/base/Headers/Foundation/*.h

Comparing the output html, I can see that some class names are not linked (like the base class in the title and the protocols), and no index.html was generated. How do I generate something like what you have on the site ?

Regards,


On Tue, Dec 6, 2011 at 2:37 PM, Richard Frith-Macdonald <address@hidden> wrote:

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.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]