> So we need to let them know the role of a class or a method clearly when we only look at the doc.
I think a good way is to add the report generated by Javadoc to the website dubbo. apache. org, we can see the effect in real time。 "what you do is what you get",。 yuhang xiu <[email protected]> 于2018年12月20日周四 上午11:05写道： > 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 > > >
