f# - para - manual de programacion android pdf

Documentación XML para métodos de interfaz y propiedades de registro

Question

Parece que la documentación XML funciona bien para la mayoría de los casos, pero no siempre. Quería que el Intellisense estuviera completamente disponible para las piezas que están diseñadas para interoperar con C #. Entonces, aquí hay un pequeño ejemplo (y tal vez un poco artificial):

///<summary>Well, it''s a summary</summary>
type Summary = {
    ///<summary>Gets a short name</summary>
    Name : string;

    ///<summary>Gets whether the action was successful or not</summary>
    IsSuccessful : bool;
}

///<summary>Represents path filtering action</summary>
type IPathFilter =
    ///<summary>Runs the filtering through the list of <paramref name="paths"/></summary>
    ///<param name="paths">A sequence of paths to check</param>
    ///<returns>A sequence of <see cref="Summary"/></returns>
    abstract member Run : seq<string> -> seq<Summary>

///<summary>A default filter</summary>
type PathFilter =

    ///<summary>Runs the filtering through the list of <paramref name="paths"/></summary>
    ///<param name="paths">A sequence of paths to check</param>
    ///<returns>A sequence of <see cref="Summary"/></returns>
    member this.Run paths=
        paths |> Seq.map (fun s -> FileInfo(s)) |> Seq.map (fun f -> { Name = f.Name; IsSuccessful = f.Exists; })

    interface IPathFilter with
        ///<summary>Runs the filtering through the list of <paramref name="paths"/></summary>
        ///<param name="paths">A sequence of paths to check</param>
        ///<returns>A sequence of <see cref="Summary"/></returns>
        member this.Run paths = 
            this.Run paths

La clase y la interfaz solo están disponibles para C # interop, una fachada para todas las cosas mágicas que suceden dentro de la biblioteca F #, por lo que no tengo que exponer las cosas específicas de F # a C #. Sería bueno tener todos los documentos disponibles en el lado C #, lo que me lleva a mis dos preguntas:

1. ¿Hay alguna manera de tener las propiedades de registro documentadas y visibles en Intellisense? Si cierro el mouse sobre el tipo en sí todo funciona, pero las propiedades no parecen ser recogidas:

2. ¿Hay alguna forma de tener una descripción "completa" de los métodos abstractos? Lo sé, desde el lado F #, solo se describen como una firma de función. Desafortunadamente, eso significa que si estoy usando la interfaz, obtendré documentos incompletos sobre el método; los nombres de los parámetros y las descripciones faltan:

   Comparado con la documentación de la clase raw:

¿Hay algo que pueda hacer, o debería simplemente aprender a vivir con eso? :)

[EDITAR]

Como notó Gustavo, los documentos de registro parecen funcionar bien en el lado F # (verificados usando VS2012 Professional):

Desafortunadamente, los mismos documentos no son visibles en C #:

:(

Answer 1

Tenga en cuenta que puede omitir la etiqueta de summary cuando no tiene otras etiquetas como params y returns . Así que esto:

///Well, it''s a summary
type Summary

es equivalente a esto:

///<summary>Well, it''s a summary</summary>
type Summary

1) Las descripciones de los campos de registro funcionan en VS2012:

2) Puede usar nombres de parámetros en métodos abstractos como este:

type IPathFilter =
    abstract member Run : paths:seq<string> -> seq<Summary>

Answer 2

Como señaló Patryk Ćwiek en el comentario anterior, Microsoft ha confirmado esto como un error. Solo para aclarar lo que realmente sucede: cuando el compilador de F # genera el archivo de documentación, en realidad documenta el campo interno en lugar de la propiedad pública del miembro de registro.

Por ejemplo, la documentación para su tipo de Summary anterior se genera como:

...
<member name="F:Test.Summary.IsSuccessful">
   <summary>Gets whether the action was successful or not</summary>
</member>
<member name="F:Test.Summary.Name">
   <summary>Gets a short name</summary>
</member>
<member name="T:Test.Summary">
   <summary>Well, it''s a summary</summary>
</member>
...

Tenga en cuenta el prefijo F: en la documentación de los nombres de los miembros. Cambie eso a P: y Visual Studio inmediatamente muestra los comentarios en su proyecto de C #. Por lo tanto, hasta que se corrija este error y la documentación se genere realmente para las propiedades, la única opción que tiene es procesar manualmente el archivo de documentación en un paso posterior a la compilación.

Por cierto, esto también explica por qué funciona en F #: Aparentemente, los enlaces F # para Visual Studio usan el campo para buscar la documentación. Esto incluso funciona en varias bibliotecas F #, a pesar de que el campo tiene visibilidad interna.

Actualización: Este error debe corregirse con F # 3.1.2. Ver también las notas de la versión .