Ignore:
Timestamp:
2014-08-14T15:33:52+02:00 (10 years ago)
Author:
Don-vip
Message:

javadoc update/cleanup

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/org/openstreetmap/josm/data/osm/DataSet.java

    r7073 r7395  
    122122    private final Object selectionLock = new Object();
    123123
     124    /**
     125     * Constructs a new {@code DataSet}.
     126     */
    124127    public DataSet() {
    125128        /*
    … …  
    130133    }
    131134
     135    /**
     136     * Returns the lock used for reading.
     137     * @return the lock used for reading
     138     */
    132139    public Lock getReadLock() {
    133140        return lock.readLock();
    … …  
    165172
    166173    /**
    167      * Maintain a list of used tags for autocompletion
     174     * Maintains a list of used tags for autocompletion.
    168175     */
    169176    private AutoCompletionManager autocomplete;
    170177
     178    /**
     179     * Returns the autocompletion manager, which maintains a list of used tags for autocompletion.
     180     * @return the autocompletion manager
     181     */
    171182    public AutoCompletionManager getAutoCompletionManager() {
    172183        if (autocomplete == null) {
    … …  
    200211    }
    201212
     213    /**
     214     * Determines if upload is being discouraged (i.e. this dataset contains private data which should not be uploaded)
     215     * @return {@code true} if upload is being discouraged, {@code false} otherwise
     216     * @see #setUploadDiscouraged
     217     */
    202218    public final boolean isUploadDiscouraged() {
    203219        return uploadDiscouraged;
    204220    }
    205221
     222    /**
     223     * Sets the "upload discouraged" flag.
     224     * @param uploadDiscouraged {@code true} if this dataset contains private data which should not be uploaded
     225     * @see #isUploadDiscouraged
     226     */
    206227    public final void setUploadDiscouraged(boolean uploadDiscouraged) {
    207228        this.uploadDiscouraged = uploadDiscouraged;
    … …  
    213234    private Map<String, String> changeSetTags = new HashMap<>();
    214235
     236    /**
     237     * Replies the set of changeset tags to be applied when or if this is ever uploaded.
     238     * @return the set of changeset tags
     239     * @see #addChangeSetTag
     240     */
    215241    public Map<String, String> getChangeSetTags() {
    216242        return changeSetTags;
    217243    }
    218244
     245    /**
     246     * Adds a new changeset tag.
     247     * @param k Key
     248     * @param v Value
     249     * @see #getChangeSetTags
     250     */
    219251    public void addChangeSetTag(String k, String v) {
    220252        this.changeSetTags.put(k,v);
    … …  
    240272    }
    241273
     274    /**
     275     * Searches for nodes in the given bounding box.
     276     * @param bbox the bounding box
     277     * @return List of nodes in the given bbox. Can be empty but not null
     278     */
    242279    public List<Node> searchNodes(BBox bbox) {
    243280        lock.readLock().lock();
    … …  
    265302    }
    266303
     304    /**
     305     * Searches for ways in the given bounding box.
     306     * @param bbox the bounding box
     307     * @return List of ways in the given bbox. Can be empty but not null
     308     */
    267309    public List<Way> searchWays(BBox bbox) {
    268310        lock.readLock().lock();
    … …  
    288330    }
    289331
     332    /**
     333     * Searches for relations in the given bounding box.
     334     * @param bbox the bounding box
     335     * @return List of relations in the given bbox. Can be empty but not null
     336     */
    290337    public List<Relation> searchRelations(BBox bbox) {
    291338        lock.readLock().lock();
    … …  
    310357
    311358    /**
    312      * @return A collection containing all primitives of the dataset. Data are not ordered
     359     * Returns a collection containing all primitives of the dataset.
     360     * @return A collection containing all primitives of the dataset. Data is not ordered
    313361     */
    314362    public Collection<OsmPrimitive> allPrimitives() {
    … …  
    317365
    318366    /**
    319      * @return A collection containing all not-deleted primitives (except keys).
     367     * Returns a collection containing all not-deleted primitives.
     368     * @return A collection containing all not-deleted primitives.
     369     * @see OsmPrimitive#isDeleted
    320370     */
    321371    public Collection<OsmPrimitive> allNonDeletedPrimitives() {
    … …  
    323373    }
    324374
     375    /**
     376     * Returns a collection containing all not-deleted complete primitives.
     377     * @return A collection containing all not-deleted complete primitives.
     378     * @see OsmPrimitive#isDeleted
     379     * @see OsmPrimitive#isIncomplete
     380     */
    325381    public Collection<OsmPrimitive> allNonDeletedCompletePrimitives() {
    326382        return getPrimitives(OsmPrimitive.nonDeletedCompletePredicate);
    327383    }
    328384
     385    /**
     386     * Returns a collection containing all not-deleted complete physical primitives.
     387     * @return A collection containing all not-deleted complete physical primitives (nodes and ways).
     388     * @see OsmPrimitive#isDeleted
     389     * @see OsmPrimitive#isIncomplete
     390     */
    329391    public Collection<OsmPrimitive> allNonDeletedPhysicalPrimitives() {
    330392        return getPrimitives(OsmPrimitive.nonDeletedPhysicalPredicate);
    331393    }
    332394
     395    /**
     396     * Returns a collection containing all modified primitives.
     397     * @return A collection containing all modified primitives.
     398     * @see OsmPrimitive#isModified
     399     */
    333400    public Collection<OsmPrimitive> allModifiedPrimitives() {
    334401        return getPrimitives(OsmPrimitive.modifiedPredicate);
    … …  
    336403
    337404    /**
    338      * Adds a primitive to the dataset
     405     * Adds a primitive to the dataset.
    339406     *
    340407     * @param primitive the primitive.
    … …  
    414481    private static final Collection<SelectionChangedListener> selListeners = new CopyOnWriteArrayList<>();
    415482
     483    /**
     484     * Adds a new selection listener.
     485     * @param listener The selection listener to add
     486     */
    416487    public static void addSelectionListener(SelectionChangedListener listener) {
    417488        ((CopyOnWriteArrayList<SelectionChangedListener>)selListeners).addIfAbsent(listener);
    418489    }
    419490
     491    /**
     492     * Removes a selection listener.
     493     * @param listener The selection listener to remove
     494     */
    420495    public static void removeSelectionListener(SelectionChangedListener listener) {
    421496        selListeners.remove(listener);
    … …  
    437512    private Collection<OsmPrimitive> selectionSnapshot;
    438513
     514    /**
     515     * Returns selected nodes and ways.
     516     * @return selected nodes and ways
     517     */
    439518    public Collection<OsmPrimitive> getSelectedNodesAndWays() {
    440519        return new FilteredCollection<>(getSelected(), new Predicate<OsmPrimitive>() {
    … …  
    447526
    448527    /**
    449      * returns an unmodifiable collection of *WaySegments* whose virtual
     528     * Returns an unmodifiable collection of *WaySegments* whose virtual
    450529     * nodes should be highlighted. WaySegments are used to avoid having
    451530     * to create a VirtualNode class that wouldn't have much purpose otherwise.
    … …  
    458537
    459538    /**
    460      * returns an unmodifiable collection of WaySegments that should be
    461      * highlighted.
     539     * Returns an unmodifiable collection of WaySegments that should be highlighted.
    462540     *
    463541     * @return unmodifiable collection of WaySegments
    … …  
    495573
    496574    /**
    497      * Return selected nodes.
     575     * Returns selected nodes.
     576     * @return selected nodes
    498577     */
    499578    public Collection<Node> getSelectedNodes() {
    … …  
    502581
    503582    /**
    504      * Return selected ways.
     583     * Returns selected ways.
     584     * @return selected ways
    505585     */
    506586    public Collection<Way> getSelectedWays() {
    … …  
    509589
    510590    /**
    511      * Return selected relations.
     591     * Returns selected relations.
     592     * @return selected relations
    512593     */
    513594    public Collection<Relation> getSelectedRelations() {
    … …  
    516597
    517598    /**
     599     * Determines whether the selection is empty or not
    518600     * @return whether the selection is empty or not
    519601     */
    … …  
    522604    }
    523605
     606    /**
     607     * Determines whether the given primitive is selected or not
     608     * @param osm the primitive
     609     * @return whether {@code osm} is selected or not
     610     */
    524611    public boolean isSelected(OsmPrimitive osm) {
    525612        return selectedPrimitives.contains(osm);
    526613    }
    527614
     615    /**
     616     * Toggles the selected state of the given collection of primitives.
     617     * @param osm The primitives to toggle
     618     */
    528619    public void toggleSelected(Collection<? extends PrimitiveId> osm) {
    529620        boolean changed = false;
    … …  
    540631        }
    541632    }
     633
     634    /**
     635     * Toggles the selected state of the given collection of primitives.
     636     * @param osm The primitives to toggle
     637     */
    542638    public void toggleSelected(PrimitiveId... osm) {
    543639        toggleSelected(Arrays.asList(osm));
    544640    }
     641
    545642    private boolean __toggleSelected(PrimitiveId primitiveId) {
    546643        OsmPrimitive primitive = getPrimitiveByIdChecked(primitiveId);
    … …  
    617714    }
    618715
     716    /**
     717     * Sets the current selection to the primitives in <code>osm</code>
     718     * and notifies all {@link SelectionChangedListener}.
     719     *
     720     * @param osm the primitives to set
     721     */
    619722    public void setSelected(PrimitiveId... osm) {
    620723        if (osm.length == 1 && osm[0] == null) {
    … …  
    627730
    628731    /**
    629      * Adds   the primitives in <code>selection</code> to the current selection
     732     * Adds the primitives in <code>selection</code> to the current selection
    630733     * and notifies all {@link SelectionChangedListener}.
    631734     *
    … …  
    636739    }
    637740
     741    /**
     742     * Adds the primitives in <code>osm</code> to the current selection
     743     * and notifies all {@link SelectionChangedListener}.
     744     *
     745     * @param osm the primitives to add
     746     */
    638747    public void addSelected(PrimitiveId... osm) {
    639748        addSelected(Arrays.asList(osm));
    … …  
    682791
    683792    /**
    684      * Remove the selection from every value in the collection.
     793     * Removes the selection from every value in the collection.
    685794     * @param osm The collection of ids to remove the selection from.
    686795     */
    … …  
    688797        clearSelection(Arrays.asList(osm));
    689798    }
     799
     800    /**
     801     * Removes the selection from every value in the collection.
     802     * @param list The collection of ids to remove the selection from.
     803     */
    690804    public void clearSelection(Collection<? extends PrimitiveId> list) {
    691805        boolean changed = false;
    … …  
    705819        }
    706820    }
     821
     822    /**
     823     * Clears the current selection.
     824     */
    707825    public void clearSelection() {
    708826        if (!selectedPrimitives.isEmpty()) {
    … …  
    715833    }
    716834
    717     @Override public DataSet clone() {
     835    @Override
     836    public DataSet clone() {
    718837        getReadLock().lock();
    719838        try {
    … …  
    776895
    777896    /**
    778      * returns a  primitive with a given id from the data set. null, if no such primitive
    779      * exists
     897     * Returns a primitive with a given id from the data set. null, if no such primitive exists
    780898     *
    781899     * @param id  uniqueId of the primitive. Might be &lt; 0 for newly created primitives
    … …  
    788906    }
    789907
     908    /**
     909     * Returns a primitive with a given id from the data set. null, if no such primitive exists
     910     *
     911     * @param primitiveId type and uniqueId of the primitive. Might be &lt; 0 for newly created primitives
     912     * @return the primitive
     913     */
    790914    public OsmPrimitive getPrimitiveById(PrimitiveId primitiveId) {
    791915        return primitivesMap.get(primitiveId);
    … …  
    9491073    }
    9501074
     1075    /**
     1076     * Adds a new data set listener.
     1077     * @param dsl The data set listener to add
     1078     */
    9511079    public void addDataSetListener(DataSetListener dsl) {
    9521080        listeners.addIfAbsent(dsl);
    9531081    }
    9541082
     1083    /**
     1084     * Removes a data set listener.
     1085     * @param dsl The data set listener to remove
     1086     */
    9551087    public void removeDataSetListener(DataSetListener dsl) {
    9561088        listeners.remove(dsl);
    … …  
    10781210    }
    10791211
     1212    /**
     1213     * Cleanups all deleted primitives (really delete them from the dataset).
     1214     */
    10801215    public void cleanupDeletedPrimitives() {
    10811216        beginUpdate();
    … …  
    11691304
    11701305    /**
    1171      * Moves all primitives and datasources from DataSet "from" to this DataSet
     1306     * Moves all primitives and datasources from DataSet "from" to this DataSet.
    11721307     * @param from The source DataSet
    11731308     */
    … …  
    11771312
    11781313    /**
    1179      * Moves all primitives and datasources from DataSet "from" to this DataSet
     1314     * Moves all primitives and datasources from DataSet "from" to this DataSet.
    11801315     * @param from The source DataSet
     1316     * @param progressMonitor The progress monitor
    11811317     */
    11821318    public void mergeFrom(DataSet from, ProgressMonitor progressMonitor) {
Note: See TracChangeset for help on using the changeset viewer.