[jira] [Created] (STORM-1048) Add generic type to conf arugment of ISpout.open

[Karl Richter (JIRA)]

Karl Richter created STORM-1048:
---

 Summary: Add generic type to conf arugment of ISpout.open
 Key: STORM-1048
 URL: https://issues.apache.org/jira/browse/STORM-1048
 Project: Apache Storm
  Issue Type: Improvement
Affects Versions: 0.10.0
Reporter: Karl Richter


Changing the signature of `ISpout.open` from `void open(Map conf, 
TopologyContext context, SpoutOutputCollector collector)` to `void 
open(Map conf, TopologyContext context, SpoutOutputCollector 
collector)` would allow, but not force callers to write typesafe code. The 
change should be backwards compatible because callers can ignore it like storm 
currently does in the `ISpout` interface.

I volunteer to do it in the complete source.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Updated] (STORM-1048) Add generic type to conf arugment of ISpout.open

[Karl Richter (JIRA)]

 [ 
https://issues.apache.org/jira/browse/STORM-1048?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Karl Richter updated STORM-1048:

Description: 
Changing the signature of `ISpout.open` from `void open(Map conf, 
TopologyContext context, SpoutOutputCollector collector)` to `void 
open(Map conf, TopologyContext context, SpoutOutputCollector 
collector)` would allow, but not force callers to write warning-free code. The 
change should be backwards compatible because callers can ignore it like storm 
currently does in the `ISpout` interface.

The changes would only avoid compiler warnings about unchecked conversations 
and rawtypes. It would make the code longer and there'd be no functional change 
as `Map` defaults to `Map` after type erasure.

Alternatively a generic type for the key and the value of `conf` could be 
introduced in `ISpout`.

I volunteer to do it in the complete source.

  was:
Changing the signature of `ISpout.open` from `void open(Map conf, 
TopologyContext context, SpoutOutputCollector collector)` to `void 
open(Map conf, TopologyContext context, SpoutOutputCollector 
collector)` would allow, but not force callers to write typesafe code. The 
change should be backwards compatible because callers can ignore it like storm 
currently does in the `ISpout` interface.

I volunteer to do it in the complete source.


> Add generic type to conf arugment of ISpout.open
> 
>
> Key: STORM-1048
> URL: https://issues.apache.org/jira/browse/STORM-1048
> Project: Apache Storm
>  Issue Type: Improvement
>Affects Versions: 0.10.0
>Reporter: Karl Richter
>
> Changing the signature of `ISpout.open` from `void open(Map conf, 
> TopologyContext context, SpoutOutputCollector collector)` to `void 
> open(Map conf, TopologyContext context, SpoutOutputCollector 
> collector)` would allow, but not force callers to write warning-free code. 
> The change should be backwards compatible because callers can ignore it like 
> storm currently does in the `ISpout` interface.
> The changes would only avoid compiler warnings about unchecked conversations 
> and rawtypes. It would make the code longer and there'd be no functional 
> change as `Map` defaults to `Map` after type erasure.
> Alternatively a generic type for the key and the value of `conf` could be 
> introduced in `ISpout`.
> I volunteer to do it in the complete source.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Created] (STORM-1049) Document central classes of storm-kafka

[Karl Richter (JIRA)]

Karl Richter created STORM-1049:
---

 Summary: Document central classes of storm-kafka
 Key: STORM-1049
 URL: https://issues.apache.org/jira/browse/STORM-1049
 Project: Apache Storm
  Issue Type: Documentation
Affects Versions: 0.10.0
Reporter: Karl Richter


The `storm-kafka` project currently is very hard to use because central 
classes, like `KafkaSpout` and `PartitionManager` are completely 
documentation-free. At least these classes should be well documented, so that 
it's possible to guess from the code what important methods do.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Updated] (STORM-1047) document internals of bin/storm.py

[Karl Richter (JIRA)]

 [ 
https://issues.apache.org/jira/browse/STORM-1047?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Karl Richter updated STORM-1047:

Description: 
The `python` script `bin/storm.py` is completely undocumented regarding it's 
internals. Function comments only include a command line interface often 
omitting an explanation of arguments and their default values (e.g. it should 
be clear why the default value of `klass` of `nimbus` is 
`"backtype.storm.daemon.nimbus"` because that doesn't make sense).

Also explanations like "Launches the nimbus daemon. [...]" (again `nimbus` 
function) is good for a command line API doc, but insufficient for a function 
documentation (should mention that it starts a `java` process and passes 
`klass` as class name to it).

How does the script use `lib/`, `extlib/` and `extlib-daemon`? It's too complex 
to squeeze this info out of the source code.

  was:
The `python` script `bin/storm.py` is completely undocumented regarding it's 
internals. Function comments only include a command line interface often 
omitting an explanation of arguments and their default values (e.g. it should 
be clear why the default value of `klass` of `nimbus` is 
`"backtype.storm.daemon.nimbus"` because that doesn't make sense).

Also explanations like "Launches the nimbus daemon. [...]" (again `nimbus` 
function) is good for a command line API doc, but insufficient for a function 
documentation (should mention that it starts a `java` process and passes 
`klass` as class name to it).


> document internals of bin/storm.py
> --
>
> Key: STORM-1047
> URL: https://issues.apache.org/jira/browse/STORM-1047
> Project: Apache Storm
>  Issue Type: Bug
>Affects Versions: 0.10.0
>Reporter: Karl Richter
>  Labels: documentation
>
> The `python` script `bin/storm.py` is completely undocumented regarding it's 
> internals. Function comments only include a command line interface often 
> omitting an explanation of arguments and their default values (e.g. it should 
> be clear why the default value of `klass` of `nimbus` is 
> `"backtype.storm.daemon.nimbus"` because that doesn't make sense).
> Also explanations like "Launches the nimbus daemon. [...]" (again `nimbus` 
> function) is good for a command line API doc, but insufficient for a function 
> documentation (should mention that it starts a `java` process and passes 
> `klass` as class name to it).
> How does the script use `lib/`, `extlib/` and `extlib-daemon`? It's too 
> complex to squeeze this info out of the source code.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Created] (STORM-1047) document internals of bin/storm.py

[Karl Richter (JIRA)]

Karl Richter created STORM-1047:
---

 Summary: document internals of bin/storm.py
 Key: STORM-1047
 URL: https://issues.apache.org/jira/browse/STORM-1047
 Project: Apache Storm
  Issue Type: Bug
Affects Versions: 0.10.0
Reporter: Karl Richter


The `python` script `bin/storm.py` is completely undocumented regarding it's 
internals. Function comments only include a command line interface often 
omitting an explanation of arguments and their default values (e.g. it should 
be clear why the default value of `klass` of `nimbus` is 
`"backtype.storm.daemon.nimbus"` because that doesn't make sense).

Also explanations like "Launches the nimbus daemon. [...]" (again `nimbus` 
function) is good for a command line API doc, but insufficient for a function 
documentation (should mention that it starts a `java` process and passes 
`klass` as class name to it).



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Created] (STORM-700) Add a hint about auto-generation in java source

[Karl Richter (JIRA)]

Karl Richter created STORM-700:
--

 Summary: Add a hint about auto-generation in java source
 Key: STORM-700
 URL: https://issues.apache.org/jira/browse/STORM-700
 Project: Apache Storm
  Issue Type: Improvement
Reporter: Karl Richter


Apparently some java classes in `storm-core` are created by a code 
generatorrefhttps://github.com/apache/storm/pull/460/ref, but there's no 
hint in the generated code about that which would be extremely helpful.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Updated] (STORM-663) Create javadocs for BoltDeclarer

[Karl Richter (JIRA)]

 [ 
https://issues.apache.org/jira/browse/STORM-663?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Karl Richter updated STORM-663:
---
Description: There's no documentation of grouping stream usage in the 
javadocs of 
BoltDeclarerrefhttp://storm.apache.org/javadoc/apidocs/backtype/storm/topology/BoltDeclarer.html/ref.
 It might be sufficient to a links to sites or HTML anchors of the full text 
documentation.  (was: There's no documentation of grouping in the javadocs of 
BoltDeclarerrefhttp://storm.apache.org/javadoc/apidocs/backtype/storm/topology/BoltDeclarer.html/ref.
 It might be sufficient to a links to sites or HTML anchors of the full text 
documentation.)

 Create javadocs for BoltDeclarer
 

 Key: STORM-663
 URL: https://issues.apache.org/jira/browse/STORM-663
 Project: Apache Storm
  Issue Type: Documentation
Affects Versions: 0.9.3
Reporter: Karl Richter

 There's no documentation of grouping stream usage in the javadocs of 
 BoltDeclarerrefhttp://storm.apache.org/javadoc/apidocs/backtype/storm/topology/BoltDeclarer.html/ref.
  It might be sufficient to a links to sites or HTML anchors of the full text 
 documentation.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Created] (STORM-665) Lower entry barrier for understanding storm's stream management

[Karl Richter (JIRA)]

Karl Richter created STORM-665:
--

 Summary: Lower entry barrier for understanding storm's stream 
management
 Key: STORM-665
 URL: https://issues.apache.org/jira/browse/STORM-665
 Project: Apache Storm
  Issue Type: Documentation
Reporter: Karl Richter


Due to the fact that storm is a stream processing framework, it's necessary to 
explain the handling of streams in a proper documentation chapter. Currently 
the index at http://storm.apache.org/doc-index.html doesn't even contain the 
word.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

[jira] [Updated] (STORM-665) Lower entry barrier for understanding storm's stream management

[Karl Richter (JIRA)]

 [ 
https://issues.apache.org/jira/browse/STORM-665?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Karl Richter updated STORM-665:
---
Description: 
Due to the fact that storm is a stream processing framework, it's necessary to 
explain the handling of streams in a proper documentation chapter. Currently 
the index at http://storm.apache.org/doc-index.html doesn't even contain the 
word.

An example of missing infos includes the usage of explicit stream ids and 
omitting them (e.g. in `BoltDeclarer.xyGrouping`). Question which arise and are 
not answered: How to declare a stream (object) explicitly? Which one is used 
when an explicit id is omitted?


  was:Due to the fact that storm is a stream processing framework, it's 
necessary to explain the handling of streams in a proper documentation chapter. 
Currently the index at http://storm.apache.org/doc-index.html doesn't even 
contain the word.


 Lower entry barrier for understanding storm's stream management
 ---

 Key: STORM-665
 URL: https://issues.apache.org/jira/browse/STORM-665
 Project: Apache Storm
  Issue Type: Documentation
Reporter: Karl Richter

 Due to the fact that storm is a stream processing framework, it's necessary 
 to explain the handling of streams in a proper documentation chapter. 
 Currently the index at http://storm.apache.org/doc-index.html doesn't even 
 contain the word.
 An example of missing infos includes the usage of explicit stream ids and 
 omitting them (e.g. in `BoltDeclarer.xyGrouping`). Question which arise and 
 are not answered: How to declare a stream (object) explicitly? Which one is 
 used when an explicit id is omitted?



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)