|
From: Harald S. <har...@fi...> - 2013-10-16 06:38:16
|
Should it matter where a developer chooses to place the comments describing a method? There are four places where a comment describing a function could be: in the interface section above and below the function, and in the implementation section above and below the function. The default behaviour of Pasdoc is to take the comment above the function in the interface section. In my mind, the comment belongs to a function. Therefore, it should come after the function declaration. The function declaration for me is the title of a text or chapter. Comments and source code are the sentences which follow it. This is not the default way for Pasdoc. It does allow for a variation. Maybe either way is fine? 2013/10/16 Marcos Rocha <mar...@us...> > I was talking with a coworker about it and we agreed that developers > hardly ever stay at interface section. Normally we (developers) stay at > implementation section, so why leave "trash" at the implementation section > instead of write them at the interface section? > Moreover, since of Delphi XE2 you can use DocInsight to see documentation > about the classes that were written at interface section. > In other hand, legacy code brings comments before procedures and functions > inside implementation section, I am moving those comments to interface > section not just to document with PasDoc, but for cleaning too. > ------------------------------ > > * [feature-requests:#46]<http://sourceforge.net/p/pasdoc/feature-requests/46/>Parse Comments in Implementation Section > * > > *Status:* open > *Created:* Tue Sep 15, 2009 05:17 PM UTC by Larry Hengen > *Last Updated:* Mon Nov 05, 2012 10:17 AM UTC > *Owner:* nobody > > PasDoc seems to work well, and I have adjusted my JavaDoc comments in > hcOPF in order to use it, until I discovered that it does not extract > comments from the implementation section. This makes it unusable as far as > I am concerned. I have rather large comment blocks at the start of each > method, and I want them to stay within the method commented so I can move > the code without losing the comment attached to it. It also makes more > sense to have the comments as close to the actual code as possible so > developers can understand the code easier by reading the comments that > appear on the screen at the same time, and more importantly update the > comments to ensure they are kept current. > > Is this feature likely to be released any time soon, or should I search > for an alternative? > ------------------------------ > > Sent from sourceforge.net because pas...@li... is > subscribed to https://sourceforge.net/p/pasdoc/feature-requests/ > > To unsubscribe from further messages, a project admin can change settings > at https://sourceforge.net/p/pasdoc/admin/feature-requests/options. Or, > if this is a mailing list, you can unsubscribe from the mailing list. > > > ------------------------------------------------------------------------------ > October Webinars: Code for Performance > Free Intel webinars can help you accelerate application performance. > Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most > from > the latest Intel processors and coprocessors. See abstracts and register > > http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk > _______________________________________________ > Pasdoc-main mailing list > Pas...@li... > https://lists.sourceforge.net/lists/listinfo/pasdoc-main > > |