Hi， On Wed, Dec 19, 2018 at 8:48 PM yuhang xiu <[email protected]> wrote: > > Hi, all > > Recently I have seen a few pr about doc. Several of them have been merged. > I think we have two issues to discuss: > 1. What kind of comments should we add? > 2. We need to define a goal. > > Regarding question one, I personally think that we should: > 1. Explain each param of the method > 2. Explain the special usage of some classes. For example, when adding the > doc of SerializableClassRegistry, we need to doc that this class only works > when using fst and kryo serialization. > 3. We need to use @link or @code for the association when the class > (method) is associated with other classes (methods).
Perhaps following some guide like [1] and [2]. But I don't think we should follow it strictly. If using IDE like Intellij IDEA, you can easily create customized Javadoc template[3], with some boilerplate content like params, return values. > > Regarding question two, I don't have a idea. Perhaps doc coverage is 40% is > a good choice. What do you think? Do you mean the average doc coverage, acoording to [4], I see there is an average of 28.8% java coverage, setting the goal of average coverage to 40%~50% looks good to me. We can do it step by step :) [1] https://www.baeldung.com/javadoc [2] https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide [3] https://stackoverflow.com/questions/17607925/how-configure-intellij-idea-javadoc-templates [4] https://github.com/apache/incubator-dubbo/issues/2884 > > > yuhang xiu <[email protected]> 于2018年12月18日周二 下午4:21写道： > > > Hello, Dave. > > > > (2) Have any committers reached out to the users who had trouble with code > >> comments to confirm these efforts will meet their concerns? > >> > > > > I used to talk to them, but I forgot to ask them about what kind of docs > > are better. > > > > But don't worry, I still have their contact details. > > I will communicate with them and hope that they will bring their opinions > > here to better work for developers who add comments. > > -- Best Regards！ Huxing
