Engee中的文档和文档

良好的文档是很好地理解和使用代码的关键。
Julia语言可以方便地使用和创建开箱即用的文档。

这本笔记本将复盖:
-在获得帮助。ngscript
-在命令行上获取帮助****
-创建自己的文档
-功能
-全局变量
-结构
-模块

还将考虑创建和连接自己的模块的方法。

得到帮助。ngscript

在获得帮助。ngscript，需要使用宏 @doc

考虑寻求帮助 sqrt.

注意文档中Markdown的使用, 和语法提示。

@doc sqrt

在命令行上获取帮助

在命令行上使用问号以获取帮助。: ?

如果您想扩展有关使用命令行的知识，请将文档读到最后。

创建自己的文档

记录功能。

为了将您自己的文档添加到函数中，您必须在函数名之前添加一个包含函数本身信息的字符串。

如果功能描述较长，建议使用triple double кавычки.

"Краткое описание функции, здоровающейся с пользователем"
function user_greeting(username::String)
    return "Hello, $(username)!"
end

user_greeting

@doc user_greeting

让我们简要地看看为什么为了使用符号 \ 和 $ мы используем raw - литерал необработанных строк:

В LaTex мы используем $\nu$ для обозначения символа ню:

Здесь сразу может возникнуть множество проблем. Внутри " "

$表示[插值](https://engee.com/helpcenter/stable/ru/julia/manual/strings.html#интерполяция ）:
\n 表示行分隔符。

因此 "$\nu$" 无法正确执行。但是，这个问题可以通过使用 raw-线路

# "$\nu$" # вызовет ошибки

@show raw"$\nu$";

raw"$\nu$" = "\$\\nu\$"

@doc raw"""
Документация, содержащая:

1. Markdown:
    - маркеры списка
    - [внешние ссылки](https://engee.com/helpcenter/stable/ru/julia/stdlib/Markdown.html)

2. Встроенный $\LaTeX$ (inline) $\frac{\sqrt{\pi}}{2}$  и отдельной формулой:
```math
\int \limits_{-\infty}^\infty e^{-x^2}\,dx = \sqrt{\pi}
```
## Смотреть также

[`документирование`](https://engee.com/helpcenter/stable/ru/julia/manual/documentation.html
), [`функции`](https://engee.com/helpcenter/stable/ru/julia/manual/functions.html)
"""
function foo()
    return nothing
end

foo

@doc foo

记录全局变量

使用全局变量时，请记住[关于问题производительности]（https://engee.com/helpcenter/stable/ru/julia/manual/performance-tips.html#избегайте-нетипизированных-глобальных-переменных ）和他们的权宜之计использования

让我们考虑几个全局变量可以同时用一个引用记录的情况。

"Ускорение свободного падения"
g_Earth, g_Moon
const g_Earth::Float64 = 9.81
const g_Moon::Float64 = 1.62

1.62

现在让我们检查两个变量是否同时存在相同的引用。:

@doc g_Earth

@doc g_Moon

请注意 const 这意味着变量的类型是常量，但不是它的值。

-更改类型时，会导致错误。**
-更改为相同类型的值时，将显示警告。

# g_Moon = "Moon"

println(g_Earth)
g_Earth = 32.
println(g_Earth)

9.81
32.0

WARNING: redefinition of constant Main.g_Earth. This may fail, cause incorrect answers, or produce other errors.

记录结构

让我们有一组相同的形状。

任务是以最紧凑的方式在平面上排列形状。然后结构将包含质量中心和图相对于水平的旋转角度。
作为[默认构造函数](https://ru.wikipedia.org/wiki/Constructor 通过沉默）选择 GeomteryShape((x=0,y=0),α=0). 您可以在[文档]中阅读有关构造函数的更多信息（https://engee.com/helpcenter/stable/ru/julia/manual/constructors.html )。

@doc """
GeometricShape((x=X,y=Y),α)

    Геометрическая фигура
- `center_of_mass`: (x=X,y=Y) - кортеж координат центра масс
- `orientation`: α - угол поворота фигуры относительно горизонтали
## Пример:
GeometricShape((x=1., y=2.), 3.)

## Возможные ошибки
1.
```julia-repl
julia> GeometricShape((4.,5.),6.)
ERROR: MethodError: no method matching GeometricShape(::Tuple{Float64, Float64}, ::Float64)

Closest candidates are:
  GeometricShape(::@NamedTuple{x::Float64, y::Float64}, ::Any)
```
**Решение:** в кортеже нужно явно указать имена полей: `GeometricShape((x=4., y=5.), 6.)`
2. 
```julia-repl
julia> GeometricShape((x=1,y=2),3.)
ERROR: MethodError: no method matching GeometricShape(::@NamedTuple{x::Int64, y::Int64}, ::Float64)

Closest candidates are:
  GeometricShape(::@NamedTuple{x::Float64, y::Float64}, ::Any)
```
**Решение:** передавайте в качетсве параметров значения типа `Float64`, а не `Int64`: GeometricShape((x=1.,y=2.),3.)
"""
struct GeometricShape
    center_of_mass::NamedTuple{(:x,:y),Tuple{Float64,Float64}}
    orientation::Float64
    GeometricShape() = new((x=0,y=0),0)  # конструктор по умолчанию
    GeometricShape((X,Y)::NamedTuple{(:x,:y),Tuple{Float64,Float64}},α)=new((x=X,y=Y),α)
end

GeometricShape

GeometricShape((x=4.,y=5.),6.)

GeometricShape((x = 4.0, y = 5.0), 6.0)

@doc GeometricShape

GeometricShape()

GeometricShape((x = 0.0, y = 0.0), 0.0)

first_shape = GeometricShape((x=1.,y=2.),3.)
first_shape.center_of_mass.y

2.0

请注意，我们结构的对象在构造后是不可变的。如果需要可变对象，它们必须是[可变结构]类型（https://engee.com/helpcenter/stable/ru/julia/manual/types.html#изменяемые-составные-типы )。

# first_shape.orientation = 4. # ОШИБКА: нельзя менять уже созданный объект

记录宏

"Макрос, здоровающийся с пользователем"
macro hellouser(username)  # создание макроса
println("Hello, $(username)!")
end

@hellouser "Peter"  # применение макроса

Hello, Peter!

要获得宏的帮助，您必须首先编写 @ 然后输入宏名称:
@macrosname

@doc @hellouser

创建和记录模块

的TemperatureScales。jl文件位于此示例的文件夹中。此文件包含一个模块 TemperatureScales.

要访问其函数和变量，您必须

使用命令转到文件夹 cd(path)，可执行文件所在的位置（documentating.ngscript)(@__DIR__). 相同的路径包含TemperatureScales。jl:

@__DIR__

"/user/Engee/Demos/Engee/Documentating"

cd(@__DIR__)

在我们的脚本中包含此模块:
通过运行命令 include("Filename.jl") julia将"包含"文件中的文本 Filename.jl 进入我们当前的脚本并执行它。（看文件的第1行 TemperatureScales.jl). 这意味着来自此文件的对象将成为我们文件的对象。

include("TemperatureScales.jl")

Greeting from TemperatureScales.jl!

Main.TemperatureScales

println(variable_from_TemperatureScales)

3

但是我们的任务是使用这个文件中的模块。模块是使用关键字创建的 module，并与 using 或 import.

using .TemperatureScales

为了确切地了解这个模块的作用，让我们调用这个模块的帮助。:

@doc TemperatureScales

让我们来看看fahr2cels函数是如何工作的。:

@doc fahr2cels

如您所见，fahr2cels帮助表示2种方法。第一个是当参数是数字时，第二个是当参数是字符串时。

现在转到命令提示符并运行

? fahr2cels

注意最后一行:
扩展帮助可与 ??.

现在退出帮助模式（通过删除 ?)

现在进入

?? fahr2cels

我们现在得到了更多的帮助。

结论

Engee中的文档非常灵活（Markdown, ）并维护一个要记录的大量对象列表：函数、变量、结构、宏和模块。

考虑在脚本中包含自定义模块。