In a class definitions contained in a VCX, you can add a Description to each
custom property and method that you define.
However, I am creating a class definitions in a PRG file, and I want to know
if there is a standard way of using comments or some other kind of markup in
the class definition to include descriptions for the properties and methods?
I don't think there is an official VFP coding rule for this, so I guess I'm
asking if there is a widely adopted standard among VFP coders who use
PRG-based classes. I know that C# has a standard way of adding descriptions
to its properties and methods, and I'm wishing (hoping) VFP has a standard
as well.
Why does this matter? Well, for one, I would hope to be able to create
documentation for the class definition (from a documentation tool) where I
could extract this description info right from the PRG. I'm not looking to
create my own format, if there is a (widely used) standard already in place.
In order for the documentation tool to work properly, it would expect the
correct format, syntax, location, etc be used consistently.
Any standard format out there?
Define Class Example as Custom
nProperty1 = 1 && Description of property goes here??
* Description of property goes here??
cProperty2 = 'SomeProp'
* Description of property goes here??
* Could span across multiple lines??
cProperty3 = 'SomeProp'
* Description of method goes here??
* Could span across multiple lines??
Procedure MethodOne(tnParameter1, tcParameter2)
*-- Code goes here
EndProc
EndDefine
As an example, here is how it's handled in C#:
This show a method definition, with the description located above it using
/// and some xml tags. Notice that you can also describe parameters.
/// <summary>
/// Updates the loaded entity with the contents from a quote object
/// </summary>
/// <param name="quote"></param>
public void UpdateEntityFromStockQuote(StockQuote quote)
{
if (this.Entity == null)
return;
if ( !string.IsNullOrEmpty(quote.Company) )
this.Entity.Company = quote.Company;
// if the price isn't set service is down or not providing data
at the moment
if ( quote.LastPrice == 0.00M )
return;
this.Entity.LastPrice = quote.LastPrice;
this.Entity.LastDate = quote.LastQuoteTime;
this.Entity.OpenPrice = quote.OpenPrice;
this.Entity.Change = quote.NetChange;
this.Entity.LastDate = quote.LastQuoteTime;
this.Entity.ItemValue = this.Entity.LastPrice * this.Entity.Qty;
}
--- StripMime Report -- processed MIME parts ---
multipart/alternative
text/plain (text body -- kept)
text/html
---
_______________________________________________
Post Messages to: ProFox@leafe.com
Subscription Maintenance: http://leafe.com/mailman/listinfo/profox
OT-free version of this list: http://leafe.com/mailman/listinfo/profoxtech
Searchable Archive: http://leafe.com/archives/search/profox
This message: http://leafe.com/archives/byMID/profox/010001cc5b65$0320fda0$0962f8e0$@com
** All postings, unless explicitly stated otherwise, are the opinions of the author, and do not constitute legal or medical advice. This statement is added to the messages for those lawyers who are too stupid to see the obvious.
Author: Tracy Pearson
Posted: 2011-08-15 13:48:08 Link
Matt Slay wrote on 2011-08-15:
> In a class definitions contained in a VCX, you can add a Description to
each
> custom property and method that you define.
>
>
> However, I am creating a class definitions in a PRG file, and I want to
know
> if there is a standard way of using comments or some other kind of markup
in
> the class definition to include descriptions for the properties and
methods?
>
>
... <snip/>
Matt,
You're bordering on a religious topic.
Many times comments don't get updated when code changes. Though when
designing a class that will be shared with others, it's nice to know what is
parameters are expected, C#'s strict rules show this. In VFP we can use the
AS clause in the LPARAMETERS to give that information.
There is a documented structure for commenting a COM object in the help.
Tracy Pearson
PowerChurch Software
_______________________________________________
Post Messages to: ProFox@leafe.com
Subscription Maintenance: http://leafe.com/mailman/listinfo/profox
OT-free version of this list: http://leafe.com/mailman/listinfo/profoxtech
Searchable Archive: http://leafe.com/archives/search/profox
This message: http://leafe.com/archives/byMID/profox/002801cc5b73$7e8e1870$7baa4950$@powerchurch.com
** All postings, unless explicitly stated otherwise, are the opinions of the author, and do not constitute legal or medical advice. This statement is added to the messages for those lawyers who are too stupid to see the obvious.
Author: Thierry Nivelet
Posted: 2011-08-16 05:55:20 Link
FWIW, here is the convention we use:
- Description in end-of-line comment at class, method and parameter level
- Each parameter is on a separate line.
DEFINE CLASS myClass AS someClass && description
PROCEDURE myProc && description
LPARAMETERS ;
Parm1; && [default value] description
, Parm2; && @ description
, etc.
'@' is mentioned if parameter is expected by reference.
I never use multi-line description as it reveals that the element's purpose is too wide and should be broken down into simpler pieces.
Based on this convention, we have an IDE-based module directory tool where one can filter on [part of] module name and/or description and several other criteria, then, by striking a key, insert a call to this module at insertion point in current code editing window.
The idea behind is to have a lot of elementary modules (10-20 lines max.) in order to:
- strictly avoid code copy-pasting and/or reinventing the wheel,
- build an ever-growing area of confidence, and performance, with existing software.
This tool could be a VFPx candidate.
Thierry Nivelet
Give your VFP app a second life in the cloud
Le 15 août 2011 à 18:04, "Matt Slay" <mattslay@jordanmachine.com> a écrit :
> In a class definitions contained in a VCX, you can add a Description to each
> custom property and method that you define.
>
>
>
> However, I am creating a class definitions in a PRG file, and I want to know
> if there is a standard way of using comments or some other kind of markup in
> the class definition to include descriptions for the properties and methods?
>
>
>
> I don't think there is an official VFP coding rule for this, so I guess I'm
> asking if there is a widely adopted standard among VFP coders who use
> PRG-based classes. I know that C# has a standard way of adding descriptions
> to its properties and methods, and I'm wishing (hoping) VFP has a standard
> as well.
>
>
>
> Why does this matter? Well, for one, I would hope to be able to create
> documentation for the class definition (from a documentation tool) where I
> could extract this description info right from the PRG. I'm not looking to
> create my own format, if there is a (widely used) standard already in place.
> In order for the documentation tool to work properly, it would expect the
> correct format, syntax, location, etc be used consistently.
>
>
>
> Any standard format out there?
>
>
>
>
>
> Define Class Example as Custom
>
>
>
> nProperty1 = 1 && Description of property goes here??
>
>
>
> * Description of property goes here??
>
> cProperty2 = 'SomeProp'
>
>
>
> * Description of property goes here??
>
> * Could span across multiple lines??
>
> cProperty3 = 'SomeProp'
>
>
>
> * Description of method goes here??
>
> * Could span across multiple lines??
>
> Procedure MethodOne(tnParameter1, tcParameter2)
>
> *-- Code goes here
>
> EndProc
>
>
>
>
>
> EndDefine
>
>
>
>
>
> As an example, here is how it's handled in C#:
>
>
>
> This show a method definition, with the description located above it using
> /// and some xml tags. Notice that you can also describe parameters.
>
>
>
> /// <summary>
>
> /// Updates the loaded entity with the contents from a quote object
>
> /// </summary>
>
> /// <param name="quote"></param>
>
> public void UpdateEntityFromStockQuote(StockQuote quote)
>
> {
>
> if (this.Entity == null)
>
> return;
>
>
>
> if ( !string.IsNullOrEmpty(quote.Company) )
>
> this.Entity.Company = quote.Company;
>
>
>
> // if the price isn't set service is down or not providing data
> at the moment
>
> if ( quote.LastPrice == 0.00M )
>
> return;
>
>
>
> this.Entity.LastPrice = quote.LastPrice;
>
> this.Entity.LastDate = quote.LastQuoteTime;
>
> this.Entity.OpenPrice = quote.OpenPrice;
>
> this.Entity.Change = quote.NetChange;
>
> this.Entity.LastDate = quote.LastQuoteTime;
>
>
>
> this.Entity.ItemValue = this.Entity.LastPrice * this.Entity.Qty;
>
> }
>
>
>
>
>
> --- StripMime Report -- processed MIME parts ---
> multipart/alternative
> text/plain (text body -- kept)
> text/html
> ---
>
[excessive quoting removed by server]
_______________________________________________
Post Messages to: ProFox@leafe.com
Subscription Maintenance: http://leafe.com/mailman/listinfo/profox
OT-free version of this list: http://leafe.com/mailman/listinfo/profoxtech
Searchable Archive: http://leafe.com/archives/search/profox
This message: http://leafe.com/archives/byMID/profox/52C3CA40-8217-45DB-9243-34B858834D7B@foxincloud.com
** All postings, unless explicitly stated otherwise, are the opinions of the author, and do not constitute legal or medical advice. This statement is added to the messages for those lawyers who are too stupid to see the obvious.