Hi, huxing I agree with what you said, we don't need to strictly follow some kind of guidance.
But I think we need a very detailed doc. And this doc is based on code, and may be more oriented to developers. So we need to let them know the role of a class or a method clearly when we only look at the doc. I'd like take a look at these doc prs and give some suggestions. Regarding the goal, I think we can increase the doc coverage rate to 45% first, and increase the coverage by about 20% first. :) Huxing Zhang <[email protected]> 于2018年12月20日周四 上午10:20写道： > 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 >
