Am Freitag, 10. April 2015, 06:22:50 schrieb xor: > On Thursday, April 09, 2015 09:27:32 PM Steve Dougherty wrote: > > What would we want to direct this development time toward? My opinion is > > that more code / features is not what Fred needs most right now. > > Full ACK on not having him work on features. > Semi-Non-ACK on what you suggested he should do, in-depth explanation below. > First here's my idea what he should do: > 1. Write package-info JavaDoc for all packages (I think he actually did that ⦠<snip lots of other JavaDoc points> > 5. Write generic documentation and tutorials on the Wiki.
I think that this would be a waste of time, except for the 5th point. I know that âwaste of timeâ sounds extreme. I say it in such strong words, because whenever I did something in Fred, it wasnât lack of JavaDoc which slowed me down. And for the subset of the code I saw, I could write JavaDoc myself with a little investigation, so we do not need toad for this. What slowed me down was the lack of practical, high level documentation. Examples: - How to write a plugin which does anything remotely useful?¹ - What callbacks are triggered when I request a key? And where do they run?² - Ĥow do Toadlets work? (turns out that that isnât that complex after all) ¹: See my try at writing a plugin tutorial, putting it off halfway because it was getting unbearable: https://d6.gnutella2.info/freenet/USK at xqbzQkEGFnFfZH3LG~ut8bjV51o~3nrIXMN3ld5Qjs0,SThdqkHICKxLZvKzMcfK4w04Y4ykcE1~lmQiskpsVqw,AQACAAE/freenet-plugin-bare/5/ ²: What does a PutHandler do, where is it fired and why is there a JokerPutHandler? https://github.com/freenet/fred/blob/c314c517e421b683f6676b109b95145151da22fc/src/freenet/client/async/BaseManifestPutter.java#L329 These issues arenât fixed by JavaDoc. They are fixed by a Hacking Guide: âFor those who come after me.â At the same time there are quite a few things which only toad can do efficiently, because only he knows the code well enough to anticipate the side effects of the changes, or where they have to be wired in. Note that documenting the API is something completely different than just throwing in JavaDoc. The FCPv2 documentation in the Wiki is an example of documentation which works: Whenever I did something with pyFreenet, that documentation helped enormously. Something like that for the Plugin API. Maybe focussed to answer the question âHow to write a plugin in such a way that it can easily be made official?â I like the idea of packaging. In addition Iâd like to see the darknet invitation bundles become reality. Itâs not hard, itâs just complex and touches lots of parts of fred. We need bundles for multiple platforms which include one or several noderefs. We need one-time tokens to avoid requiring an initial noderef exchange, we need darknet FOAF routing. All this has been planned in detail in the bugtracker. And it can be done in small, self-contained steps which I would think that toad can do over summer. Packaging makes opennet easier: apt-get cannot give you darknet references. Thatâs useful, because it can give us many more users, and it makes it easy for developers to use Freenet as communication backend: Just add a dependency when you package your program. Together this would give tangible deliverables: - A HACKING guide: âFor those who come after meâ. - Documentation for the Plugin API which is easy to follow and answers the question how to create a plugin we can easily make official. - A package for Debian, maybe also for Fedora. Together those should cover most distros. - The ability to create bundles from the web interface which allow one friend to connect without further non-freenet communication. 3 weeks each would give solid 12 weeks of full-time work. Best wishes, Arne -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 299 bytes Desc: This is a digitally signed message part. URL: <https://emu.freenetproject.org/pipermail/devl/attachments/20150410/32e4d016/attachment.sig>
