[tor-bugs] #13004 [Onionoo]: Decide what documentation should exist for Onionoo

[Tor Bug Tracker & Wiki]

#13004: Decide what documentation should exist for Onionoo
-----------------------------+-----------------
     Reporter:  karsten      |      Owner:
         Type:  enhancement  |     Status:  new
     Priority:  normal       |  Milestone:
    Component:  Onionoo      |    Version:
   Resolution:               |   Keywords:
Actual Points:               |  Parent ID:
       Points:               |
-----------------------------+-----------------

Comment (by iwakeh):

 == Documentation for Users
 The getting started guide is a good idea.
 Once someone really wants to write a client they will have to read
 protocol.html (which is very well written and was very useful as a
 reference when I started working on koninoo).

 I cannot make sense of the following sentence (line 38):
 ''A positive side effect of making Onionoo's protocol specification as
 precise and useful as possible is that the documentation of Onionoo
 clients is more likely to be useful.''

 == Documentation for Potential Contributors
 FAQs might be useful for things like
 * maven vs. ant
 * Why are certain java libs not up-to-date
 * Which java libs could be used for Onionoo development
 * etc. etc.
 (You probably already have a collection of some of these questions
 anyway?)

 It's ok to remove the DESIGN doc. Such docs usually only describe hopes
 and plans,
 but hardly facts. The important decisions should show up in the FAQs and
 javadoc.

 Well, other than that, source code **is** self explanatory :-)
 I agree, javadoc should be added for all interfaces and public methods.
 (The, soon to be available, client-api could try to provide that from
 scratch.)
 And, this should be a rule in the contributor guide, too.

 Package javadoc is a good place for a overviews.
 (btw: Since javadoc 5 it is recommended to use {{{package-info.java}}},
 cf.
 [http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html
 this], search for paragraph **Package Comment Files**.)


 == Contributor Guide
 In addition to the topics you mention I would propose
 ''Coding Rules'' or a ''Design Guide'' for contributors.

 This would contain:
 * naming rules for variables and methods
 * the above mentioned javadoc rule
 * a big no to uses of {{{System.out}}} or {{{System.err}}} as soon as
 logging is in place
 * rules about when to use external apis
 * and some more.
 Maybe a reference to some standard java coding guides for defaults?

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/13004#comment:2>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online