Ticket #16873: suggestions.plain.diff

File suggestions.plain.diff, 8.1 KB (added by iwakeh, 4 years ago)
  • build.xml

    diff --git a/build.xml b/build.xml
    index 81c2fbd..129c4ed 100644
    a b  
    11<project default="jar" name="descriptor" basedir=".">
    22  <property name="release.version" value="1.1.0-dev" />
    33  <property name="sources" value="src"/>
     4  <property name="resources" value="resources"/>
    45  <property name="classes" value="classes"/>
    56  <property name="docs" value="javadoc"/>
    67  <property name="tests" value="test"/>
     
    5758    <javadoc destdir="${docs}"
    5859             footer="&amp;copy; 2016 The Tor Project"
    5960             doctitle="DescripTor API Documentation"
     61             overview="${basedir}/${resources}/overview.html"
    6062             use="true"
    6163             windowtitle="DescripTor API Documentation">
    6264      <classpath refid="classpath"/>
  • new file resources/overview.html

    diff --git a/resources/overview.html b/resources/overview.html
    new file mode 100644
    index 0000000..531057e
    - +  
     1<html>
     2  <body>
     3    <p>DescripTor API, which is provided and supported by Tor's Metrics-Team,
     4      is a library to obtain and process descriptors containing Tor network data.
     5      It is the main Java tool for processing Tor descriptors and
     6      provides a standard API consisting of interfaces and a reference
     7      implementation for all of them.</p>
     8
     9    <p>The interfaces in
     10      <a href="./org/torproject/descriptor/package-summary.html">{@code org.torproject.descriptor}</a>
     11      as well as their implementations in
     12      the {@code org.torproject.descriptor.impl} package were driven by two
     13      main goals originating from the primary use case to make Tor network
     14      data accessible for statistical analysis:</p>
     15
     16    <ul>
     17      <li><em>Complete coverage:</em> This library is supposed to cover the
     18        complete range of Tor descriptors made available by the
     19        <a href="https://collector.torproject.org">CollecTor</a>
     20        service.</li>
     21      <li><em>Runtime and memory efficiency:</em> Processing large amounts of
     22        descriptors in bulk is supposed to be efficient in terms of runtime and
     23        required memory.</li>
     24    </ul>
     25
     26    <p>At the same time the current design and implementation were done
     27      with a number of non-goals in mind, even though some of these might
     28      turn into goals in the future:</p>
     29
     30    <p><ul>
     31      <li><em>Verification:</em> The descriptor parser performs some basic
     32        verifications of descriptor formats, but no cryptographic
     33        verifications.  It may not even be possible to write a cryptographic
     34        verification tool using parsed descriptor contents, though this has not
     35        been attempted yet.</li>
     36      <li><em>Potentially lossy conversion:</em> Descriptor contents may be
     37        converted to a format that is easier to process, even if that
     38        conversion makes it harder or impossible to re-create the original
     39        descriptor contents from a parsed descriptor.</li>
     40      <li><em>Generating descriptors:</em> This library does not contain any
     41        functionality to generate new descriptors for testing or related
     42        purposes, neither from previously set data nor randomly.</li>
     43      <li><em>Writing descriptors:</em> This library does not support writing
     44        descriptors to the file system or a database, both of which are left to
     45        the application.  Stated differently, there are no descriptor sinks
     46        that would correspond to the provided descriptor sources.</li>
     47    </ul></p>
     48
     49    <p>Hints about using DescripTor can be found in the
     50      <a href="./org/torproject/descriptor/package-summary.html#package.description">{@code org.torproject.descriptor} package description</a>.
     51    </p>
     52
     53    <p>Contact and further information:
     54      <ul>
     55        <li><a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Metrics%2Fmetrics-lib">DescripTor bugs and tickets</a></li>
     56        <li><a href="https://lists.torproject.org/cgi-bin/mailman/listinfo/metrics-team">Metrics-Team Mailing List</a></li>
     57        <li><a href="https://trac.torproject.org/projects/tor/wiki/org/teams/MetricsTeam">Metrics-Team Web-Site</a></li>
     58      </ul>
     59  </body>
     60</html>
  • src/org/torproject/descriptor/DescriptorSourceFactory.java

    diff --git a/src/org/torproject/descriptor/DescriptorSourceFactory.java b/src/org/torproject/descriptor/DescriptorSourceFactory.java
    index 8622c3c..8eb0bc7 100644
    a b package org.torproject.descriptor; 
    1717 * own impl package.  This may be overridden by setting Java properties,
    1818 * though most users will simply use the default implementations.</p>
    1919 *
     20 * <p>These properties can be used for setting the implementation:
     21 * <ul>
     22 *   <li>{@code descriptor.collector}</li>
     23 *   <li>{@code descriptor.downloader}</li>
     24 *   <li>{@code descriptor.parser}</li>
     25 *   <li>{@code descriptor.reader}</li>
     26 * </ul></p>
     27 *
     28 * <p>Assuming the classpath contains the special implementation referenced,
     29 * your application classes as well as a descriptor API jar the following is an
     30 * example for using a different implementation of the descriptor downloader:</p>
     31 *
     32 * <p><code>
     33 *  java -Ddescriptor.downloader=my.special.descriptorimpl.Downloader my.app.Mainclass
     34 * </code></p>
     35 *
    2036 * @since 1.0.0
    2137 */
    2238public final class DescriptorSourceFactory {
  • src/org/torproject/descriptor/package-info.java

    diff --git a/src/org/torproject/descriptor/package-info.java b/src/org/torproject/descriptor/package-info.java
    index d444bc2..5b34554 100644
    a b  
    55 * Interfaces and essential classes for obtaining and processing Tor
    66 * descriptors.
    77 *
    8  * <p>This is a library to obtain and process descriptors containing Tor
    9  * network data.  This package contains all relevant interfaces and
     8 * <p>This package contains all relevant interfaces and
    109 * classes that an application would need to use this library.
    1110 * Applications are strongly discouraged from accessing types from the
    1211 * implementation package ({@code org.torproject.descriptor.impl})
     
    7574 * ({@link org.torproject.descriptor.TorperfResult}).</li>
    7675 * </ol>
    7776 *
    78  * <p>The interfaces in this package as well as their implementations in
    79  * the {@code org.torproject.descriptor.impl} package were driven by two
    80  * main goals originating from the primary use case to make Tor network
    81  * data accessible for statistical analysis:</p>
    82  *
    83  * <ul>
    84  * <li><em>Complete coverage:</em> This library is supposed to cover the
    85  * complete range of Tor descriptors made available by the CollecTor
    86  * service.</li>
    87  * <li><em>Runtime and memory efficiency:</em> Processing large amounts of
    88  * descriptors in bulk is supposed to be efficient in terms of runtime and
    89  * required memory.</li>
    90  * </ul>
    91  *
    92  * <p>At the same time the current design and implementation were done
    93  * with a number of non-goals in mind, even though some of these might
    94  * turn into goals in the future:</p>
    95  *
    96  * <ul>
    97  * <li><em>Verification:</em> The descriptor parser performs some basic
    98  * verifications of descriptor formats, but no cryptographic
    99  * verifications.  It may not even be possible to write a cryptographic
    100  * verification tool using parsed descriptor contents, though this has not
    101  * been attempted yet.</li>
    102  * <li><em>Potentially lossy conversion:</em> Descriptor contents may be
    103  * converted to a format that is easier to process, even if that
    104  * conversion makes it harder or impossible to re-create the original
    105  * descriptor contents from a parsed descriptor.</li>
    106  * <li><em>Generating descriptors:</em> This library does not contain any
    107  * functionality to generate new descriptors for testing or related
    108  * purposes, neither from previously set data nor randomly.</li>
    109  * <li><em>Writing descriptors:</em> This library does not support writing
    110  * descriptors to the file system or a database, both of which are left to
    111  * the application.  Stated differently, there are no descriptor sinks
    112  * that would correspond to the provided descriptor sources.</li>
    113  * </ul>
    114  *
    11577 * @since 1.0.0
    11678 */
    11779package org.torproject.descriptor;